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-2013, 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 Lib.Util; use Lib.Util; 31with Put_SPARK_Xrefs; 32 33package 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 : 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_String_Subtype => 'S', 506 E_String_Type => 'S', 507 E_Subprogram_Type => ' ', 508 E_Task_Subtype => 'T', 509 E_Task_Type => 'T', 510 E_Variable => '*', 511 E_Void => ' ', 512 513 -- The following entities are not ones to which we gather the cross- 514 -- references, since it does not make sense to do so (e.g. references to 515 -- a package are to the spec, not the body) Indeed the occurrence of the 516 -- body entity is considered to be a reference to the spec entity. 517 518 E_Package_Body => ' ', 519 E_Protected_Body => ' ', 520 E_Protected_Object => ' ', 521 E_Subprogram_Body => ' ', 522 E_Task_Body => ' '); 523 524 -- The following table is for information purposes. It shows the use of 525 -- each character appearing as an entity type. 526 527 -- letter lower case usage UPPER CASE USAGE 528 529 -- a array object (except string) array type (except string) 530 -- b Boolean object Boolean type 531 -- c class-wide object class-wide type 532 -- d decimal fixed-point object decimal fixed-point type 533 -- e non-Boolean enumeration object non_Boolean enumeration type 534 -- f floating-point object floating-point type 535 -- g C/C++ macro C/C++ fun-like macro 536 -- h Interface (Ada 2005) Abstract type 537 -- i signed integer object signed integer type 538 -- j C++ class object C++ class 539 -- k generic package package 540 -- l label on loop label on statement 541 -- m modular integer object modular integer type 542 -- n enumeration literal named number 543 -- o ordinary fixed-point object ordinary fixed-point type 544 -- p access object access type 545 -- q label on block C/C++ include file 546 -- r record object record type 547 -- s string object string type 548 -- t task object task type 549 -- u generic procedure procedure 550 -- v generic function or operator function or operator 551 -- w protected object protected type 552 -- x abstract procedure exception 553 -- y abstract function entry or entry family 554 -- z generic formal parameter (unused) 555 556 --------------------------------------------------- 557 -- Handling of Imported and Exported Subprograms -- 558 --------------------------------------------------- 559 560 -- If a pragma Import or Interface applies to a subprogram, the pragma is 561 -- the completion of the subprogram. This is noted in the ALI file by 562 -- making the occurrence of the subprogram in the pragma into a body 563 -- reference ('b') and by including the external name of the subprogram and 564 -- its language, bracketed by '<' and '>' in that reference. For example: 565 566 -- 3U13*imported_proc 4b<c,there>21 567 568 -- indicates that procedure imported_proc, declared at line 3, has a pragma 569 -- Import at line 4, that its body is in C, and that the link name as given 570 -- in the pragma is "there". 571 572 -- If a pragma Export applies to a subprogram exported to a foreign 573 -- language (ie. the pragma has convention different from Ada), then the 574 -- pragma is annotated in the ALI file by making the occurrence of the 575 -- subprogram in the pragma into an implicit reference ('i') and by 576 -- including the external name of the subprogram and its language, 577 -- bracketed by '<' and '>' in that reference. For example: 578 579 -- 3U13*exported_proc 4i<c,here>21 580 581 -- indicates that procedure exported_proc, declared at line 3, has a pragma 582 -- Export at line 4, that its body is exported to C, and that the link name 583 -- as given in the pragma is "here". 584 585 ------------------------- 586 -- Deferred_References -- 587 ------------------------- 588 589 -- Normally we generate references as we go along, but as discussed in 590 -- Sem_Util.Is_LHS, and Sem_Ch8.Find_Direct_Name/Find_Selected_Component, 591 -- we have one case where that is tricky, which is when we have something 592 -- like X.A := 3, where we don't know until we know the type of X whether 593 -- this is a reference (if X is an access type, so what we really have is 594 -- X.all.A := 3) or a modification, where X is not an access type. 595 596 -- What we do in such cases is to gather nodes, where we would have liked 597 -- to call Generate_Reference but we couldn't because we didn't know enough 598 -- into this table, Then we deal with generating references later on when 599 -- we have sufficient information to do it right. 600 601 type Deferred_Reference_Entry is record 602 E : Entity_Id; 603 N : Node_Id; 604 end record; 605 -- One entry, E, N are as required for Generate_Reference call 606 607 package Deferred_References is new Table.Table ( 608 Table_Component_Type => Deferred_Reference_Entry, 609 Table_Index_Type => Int, 610 Table_Low_Bound => 0, 611 Table_Initial => 512, 612 Table_Increment => 200, 613 Table_Name => "Name_Deferred_References"); 614 615 procedure Process_Deferred_References; 616 -- This procedure is called from Frontend to process these table entries. 617 618 ----------------------------- 619 -- SPARK Xrefs Information -- 620 ----------------------------- 621 622 -- This package defines procedures for collecting SPARK cross-reference 623 -- information and printing in ALI files. 624 625 package SPARK_Specific is 626 627 function Enclosing_Subprogram_Or_Package (N : Node_Id) return Entity_Id; 628 -- Return the closest enclosing subprogram of package 629 630 procedure Generate_Dereference 631 (N : Node_Id; 632 Typ : Character := 'r'); 633 -- This procedure is called to record a dereference. N is the location 634 -- of the dereference. 635 636 type Node_Processing is access procedure (N : Node_Id); 637 638 procedure Traverse_Compilation_Unit 639 (CU : Node_Id; 640 Process : Node_Processing; 641 Inside_Stubs : Boolean); 642 -- Call Process on all declarations in compilation unit CU. If 643 -- Inside_Stubs is True, then the body of stubs is also traversed. 644 -- Generic declarations are ignored. 645 646 procedure Traverse_All_Compilation_Units (Process : Node_Processing); 647 -- Call Process on all declarations through all compilation units. 648 -- Generic declarations are ignored. 649 650 procedure Collect_SPARK_Xrefs 651 (Sdep_Table : Unit_Ref_Table; 652 Num_Sdep : Nat); 653 -- Collect SPARK cross-reference information from library units (for 654 -- files and scopes) and from shared cross-references. Fill in the 655 -- tables in library package called SPARK_Xrefs. 656 657 procedure Output_SPARK_Xrefs is new Put_SPARK_Xrefs; 658 -- Output SPARK cross-reference information to the ALI files, based on 659 -- the information collected in the tables in library package called 660 -- SPARK_Xrefs, and using routines in Lib.Util. 661 662 end SPARK_Specific; 663 664 ----------------- 665 -- Subprograms -- 666 ----------------- 667 668 procedure Generate_Definition (E : Entity_Id); 669 -- Records the definition of an entity 670 671 procedure Generate_Operator_Reference 672 (N : Node_Id; 673 T : Entity_Id); 674 -- Node N is an operator node, whose entity has been set. If this entity 675 -- is a user defined operator (i.e. an operator not defined in package 676 -- Standard), then a reference to the operator is recorded at node N. 677 -- T is the operand type of the operator. A reference to the operator is an 678 -- implicit reference to the type, and that needs to be recorded to avoid 679 -- spurious warnings on unused entities, when the operator is a renaming of 680 -- a predefined operator. 681 682 procedure Generate_Reference 683 (E : Entity_Id; 684 N : Node_Id; 685 Typ : Character := 'r'; 686 Set_Ref : Boolean := True; 687 Force : Boolean := False); 688 -- This procedure is called to record a reference. N is the location of the 689 -- reference and E is the referenced entity. Typ is one of: 690 -- 691 -- a character already described in the description of ref entries above 692 -- ' ' for dummy reference (see below) 693 -- 694 -- Note: all references to incomplete or private types are to the original 695 -- (incomplete or private type) declaration. The full declaration is 696 -- treated as a reference with type 'c'. 697 -- 698 -- Note: all references to packages or subprograms are to the entity for 699 -- the spec. The entity in the body is treated as a reference with type 700 -- 'b'. Similar handling for references to subprogram formals. 701 -- 702 -- The call has no effect if N is not in the extended main source unit 703 -- This check is omitted for type 'e' references (where it is useful to 704 -- have structural scoping information for other than the main source), 705 -- and for 'p' (since we want to pick up inherited primitive operations 706 -- that are defined in other packages). 707 -- 708 -- The call also has no effect if any of the following conditions hold: 709 -- 710 -- cross-reference collection is disabled 711 -- entity does not come from source (and Force is False) 712 -- reference does not come from source (and Force is False) 713 -- the entity is not one for which xrefs are appropriate 714 -- the type letter is blank 715 -- the node N is not an identifier, defining identifier, or expanded name 716 -- the type is 'p' and the entity is not in the extended main source 717 -- 718 -- If all these conditions are met, then the Is_Referenced flag of E is set 719 -- (unless Set_Ref is False) and a cross-reference entry is recorded for 720 -- later output when Output_References is called. 721 -- 722 -- Note: the dummy space entry is for the convenience of some callers, 723 -- who find it easier to pass a space to suppress the entry than to do 724 -- a specific test. The call has no effect if the type is a space. 725 -- 726 -- The parameter Set_Ref is normally True, and indicates that in addition 727 -- to generating a cross-reference, the Referenced flag of the specified 728 -- entity should be set. If this parameter is False, then setting of the 729 -- Referenced flag is inhibited. 730 -- 731 -- The parameter Force is set to True to force a reference to be generated 732 -- even if Comes_From_Source is false. This is used for certain implicit 733 -- references, and also for end label references. 734 735 procedure Generate_Reference_To_Formals (E : Entity_Id); 736 -- Add a reference to the definition of each formal on the line for 737 -- a subprogram or an access_to_subprogram type. 738 739 procedure Generate_Reference_To_Generic_Formals (E : Entity_Id); 740 -- Add a reference to the definition of each generic formal on the line 741 -- for a generic unit. 742 743 procedure Output_References; 744 -- Output references to the current ali file 745 746 procedure Initialize; 747 -- Initialize internal tables 748 749end Lib.Xref; 750