gcc/ada/sinput.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                               S I N P U T                                --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --          Copyright (C) 1992-2008, 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 -- As a special exception,  if other files  instantiate  generics from this --
  23 -- unit, or you link  this unit with other files  to produce an executable, --
  24 -- this  unit  does not  by itself cause  the resulting  executable  to  be --
  25 -- covered  by the  GNU  General  Public  License.  This exception does not --
  26 -- however invalidate  any other reasons why  the executable file  might be --
  27 -- covered by the  GNU Public License.                                      --
  28 --                                                                          --
  29 -- GNAT was originally developed  by the GNAT team at  New York University. --
  30 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  31 --                                                                          --
  32 ------------------------------------------------------------------------------
  33
  34 --  This package contains the input routines used for reading the
  35 --  input source file. The actual I/O routines are in OS_Interface,
  36 --  with this module containing only the system independent processing.
  37
  38 --  General Note: throughout the compiler, we use the term line or source
  39 --  line to refer to a physical line in the source, terminated by the end of
  40 --  physical line sequence.
  41
  42 --  There are two distinct concepts of line terminator in GNAT
  43
  44 --    A logical line terminator is what corresponds to the "end of a line" as
  45 --    described in RM 2.2 (13). Any of the characters FF, LF, CR or VT or any
  46 --    wide character that is a Line or Paragraph Separator acts as an end of
  47 --    logical line in this sense, and it is essentially irrelevant whether one
  48 --    or more appears in sequence (since if sequence of such characters is
  49 --    regarded as separate ends of line, then the intervening logical lines
  50 --    are null in any case).
  51
  52 --    A physical line terminator is a sequence of format effectors that is
  53 --    treated as ending a physical line. Physical lines have no Ada semantic
  54 --    significance, but they are significant for error reporting purposes,
  55 --    since errors are identified by line and column location.
  56
  57 --  In GNAT, a physical line is ended by any of the sequences LF, CR/LF, CR or
  58 --  LF/CR. LF is used in typical Unix systems, CR/LF in DOS systems, and CR
  59 --  alone in System 7. We don't know of any system using LF/CR, but it seems
  60 --  reasonable to include this case for consistency. In addition, we recognize
  61 --  any of these sequences in any of the operating systems, for better
  62 --  behavior in treating foreign files (e.g. a Unix file with LF terminators
  63 --  transferred to a DOS system). Finally, wide character codes in categories
  64 --  Separator, Line and Separator, Paragraph are considered to be physical
  65 --  line terminators.
  66
  67 with Alloc;
  68 with Casing; use Casing;
  69 with Namet;  use Namet;
  70 with Table;
  71 with Types;  use Types;
  72
  73 package Sinput is
  74
  75    type Type_Of_File is (
  76    --  Indicates type of file being read
  77
  78       Src,
  79       --  Normal Ada source file
  80
  81       Config,
  82       --  Configuration pragma file
  83
  84       Def,
  85       --  Preprocessing definition file
  86
  87       Preproc);
  88       --  Source file with preprocessing commands to be preprocessed
  89
  90    ----------------------------
  91    -- Source License Control --
  92    ----------------------------
  93
  94    --  The following type indicates the license state of a source if it
  95    --  is known.
  96
  97    type License_Type is
  98      (Unknown,
  99       --  Licensing status of this source unit is unknown
 100
 101       Restricted,
 102       --  This is a non-GPL'ed unit that is restricted from depending
 103       --  on GPL'ed units (e.g. proprietary code is in this category)
 104
 105       GPL,
 106       --  This file is licensed under the unmodified GPL. It is not allowed
 107       --  to depend on Non_GPL units, and Non_GPL units may not depend on
 108       --  this source unit.
 109
 110       Modified_GPL,
 111       --  This file is licensed under the GNAT modified GPL (see header of
 112       --  This file for wording of the modification). It may depend on other
 113       --  Modified_GPL units or on unrestricted units.
 114
 115       Unrestricted);
 116       --  The license on this file is permitted to depend on any other
 117       --  units, or have other units depend on it, without violating the
 118       --  license of this unit. Examples are public domain units, and
 119       --  units defined in the RM).
 120
 121    --  The above license status is checked when the appropriate check is
 122    --  activated and one source depends on another, and the licensing state
 123    --  of both files is known:
 124
 125    --  The prohibited combinations are:
 126
 127    --    Restricted file may not depend on GPL file
 128
 129    --    GPL file may not depend on Restricted file
 130
 131    --    Modified GPL file may not depend on Restricted file
 132    --    Modified_GPL file may not depend on GPL file
 133
 134    --  The reason for the last restriction here is that a client depending
 135    --  on a modified GPL file must be sure that the license condition is
 136    --  correct considered transitively.
 137
 138    --  The licensing status is determined either by the presence of a
 139    --  specific pragma License, or by scanning the header for a predefined
 140    --  file, or any file if compiling in -gnatg mode.
 141
 142    -----------------------
 143    -- Source File Table --
 144    -----------------------
 145
 146    --  The source file table has an entry for each source file read in for
 147    --  this run of the compiler. This table is (default) initialized when
 148    --  the compiler is loaded, and simply accumulates entries as compilation
 149    --  proceeds and various routines in Sinput and its child packages are
 150    --  called to load required source files.
 151
 152    --  Virtual entries are also created for generic templates when they are
 153    --  instantiated, as described in a separate section later on.
 154
 155    --  In the case where there are multiple main units (e.g. in the case of
 156    --  the cross-reference tool), this table is not reset between these units,
 157    --  so that a given source file is only read once if it is used by two
 158    --  separate main units.
 159
 160    --  The entries in the table are accessed using a Source_File_Index that
 161    --  ranges from 1 to Last_Source_File. Each entry has the following fields
 162
 163    --  Note: fields marked read-only are set by Sinput or one of its child
 164    --  packages when a source file table entry is created, and cannot be
 165    --  subsequently modified, or alternatively are set only by very special
 166    --  circumstances, documented in the comments.
 167
 168    --  File_Name : File_Name_Type (read-only)
 169    --    Name of the source file (simple name with no directory information)
 170
 171    --  Full_File_Name : File_Name_Type (read-only)
 172    --    Full file name (full name with directory info), used for generation
 173    --    of error messages, etc.
 174
 175    --  File_Type : Type_Of_File (read-only)
 176    --    Indicates type of file (source file, configuration pragmas file,
 177    --    preprocessor definition file, preprocessor input file).
 178
 179    --  Reference_Name : File_Name_Type (read-only)
 180    --    Name to be used for source file references in error messages where
 181    --    only the simple name of the file is required. Identical to File_Name
 182    --    unless pragma Source_Reference is used to change it. Only processing
 183    --    for the Source_Reference pragma circuit may set this field.
 184
 185    --  Full_Ref_Name : File_Name_Type (read-only)
 186    --    Name to be used for source file references in error messages where
 187    --    the full name of the file is required. Identical to Full_File_Name
 188    --    unless pragma Source_Reference is used to change it. Only processing
 189    --    for the Source_Reference pragma may set this field.
 190
 191    --  Debug_Source_Name : File_Name_Type (read-only)
 192    --    Name to be used for source file references in debugging information
 193    --    where only the simple name of the file is required. Identical to
 194    --    Reference_Name unless the -gnatD (debug source file) switch is used.
 195    --    Only processing in Sprint that generates this file is permitted to
 196    --    set this field.
 197
 198    --  Full_Debug_Name : File_Name_Type (read-only)
 199    --    Name to be used for source file references in debugging information
 200    --    where the full name of the file is required. This is identical to
 201    --    Full_Ref_Name unless the -gnatD (debug source file) switch is used.
 202    --    Only processing in Sprint that generates this file is permitted to
 203    --    set this field.
 204
 205    --  License : License_Type;
 206    --    License status of source file
 207
 208    --  Num_SRef_Pragmas : Nat;
 209    --    Number of source reference pragmas present in source file
 210
 211    --  First_Mapped_Line : Logical_Line_Number;
 212    --    This field stores logical line number of the first line in the
 213    --    file that is not a Source_Reference pragma. If no source reference
 214    --    pragmas are used, then the value is set to No_Line_Number.
 215
 216    --  Source_Text : Source_Buffer_Ptr (read-only)
 217    --    Text of source file. Note that every source file has a distinct set
 218    --    of non-overlapping logical bounds, so it is possible to determine
 219    --    which file is referenced from a given subscript (Source_Ptr) value.
 220
 221    --  Source_First : Source_Ptr; (read-only)
 222    --    Subscript of first character in Source_Text. Note that this cannot
 223    --    be obtained as Source_Text'First, because we use virtual origin
 224    --    addressing.
 225
 226    --  Source_Last : Source_Ptr; (read-only)
 227    --    Subscript of last character in Source_Text. Note that this cannot
 228    --    be obtained as Source_Text'Last, because we use virtual origin
 229    --    addressing, so this value is always Source_Ptr'Last.
 230
 231    --  Time_Stamp : Time_Stamp_Type; (read-only)
 232    --    Time stamp of the source file
 233
 234    --  Source_Checksum : Word;
 235    --    Computed checksum for contents of source file. See separate section
 236    --    later on in this spec for a description of the checksum algorithm.
 237
 238    --  Last_Source_Line : Physical_Line_Number;
 239    --    Physical line number of last source line. While a file is being
 240    --    read, this refers to the last line scanned. Once a file has been
 241    --    completely scanned, it is the number of the last line in the file,
 242    --    and hence also gives the number of source lines in the file.
 243
 244    --  Keyword_Casing : Casing_Type;
 245    --    Casing style used in file for keyword casing. This is initialized
 246    --    to Unknown, and then set from the first occurrence of a keyword.
 247    --    This value is used only for formatting of error messages.
 248
 249    --  Identifier_Casing : Casing_Type;
 250    --    Casing style used in file for identifier casing. This is initialized
 251    --    to Unknown, and then set from an identifier in the program as soon as
 252    --    one is found whose casing is sufficiently clear to make a decision.
 253    --    This value is used for formatting of error messages, and also is used
 254    --    in the detection of keywords misused as identifiers.
 255
 256    --  Instantiation : Source_Ptr;
 257    --    Source file location of the instantiation if this source file entry
 258    --    represents a generic instantiation. Set to No_Location for the case
 259    --    of a normal non-instantiation entry. See section below for details.
 260    --    This field is read-only for clients.
 261
 262    --  Inlined_Body : Boolean;
 263    --    This can only be set True if Instantiation has a value other than
 264    --    No_Location. If true it indicates that the instantiation is actually
 265    --    an instance of an inlined body.
 266
 267    --  Template : Source_File_Index; (read-only)
 268    --    Source file index of the source file containing the template if this
 269    --    is a generic instantiation. Set to No_Source_File for the normal case
 270    --    of a non-instantiation entry. See Sinput-L for details.
 271
 272    --  Unit : Unit_Number_Type;
 273    --    Identifies the unit contained in this source file. Set by
 274    --    Initialize_Scanner, must not be subsequently altered.
 275
 276    --  The source file table is accessed by clients using the following
 277    --  subprogram interface:
 278
 279    subtype SFI is Source_File_Index;
 280
 281    System_Source_File_Index : SFI;
 282    --  The file system.ads is always read by the compiler to determine the
 283    --  settings of the target parameters in the private part of System. This
 284    --  variable records the source file index of system.ads. Typically this
 285    --  will be 1 since system.ads is read first.
 286
 287    function Debug_Source_Name (S : SFI) return File_Name_Type;
 288    function File_Name         (S : SFI) return File_Name_Type;
 289    function File_Type         (S : SFI) return Type_Of_File;
 290    function First_Mapped_Line (S : SFI) return Logical_Line_Number;
 291    function Full_Debug_Name   (S : SFI) return File_Name_Type;
 292    function Full_File_Name    (S : SFI) return File_Name_Type;
 293    function Full_Ref_Name     (S : SFI) return File_Name_Type;
 294    function Identifier_Casing (S : SFI) return Casing_Type;
 295    function Inlined_Body      (S : SFI) return Boolean;
 296    function Instantiation     (S : SFI) return Source_Ptr;
 297    function Keyword_Casing    (S : SFI) return Casing_Type;
 298    function Last_Source_Line  (S : SFI) return Physical_Line_Number;
 299    function License           (S : SFI) return License_Type;
 300    function Num_SRef_Pragmas  (S : SFI) return Nat;
 301    function Reference_Name    (S : SFI) return File_Name_Type;
 302    function Source_Checksum   (S : SFI) return Word;
 303    function Source_First      (S : SFI) return Source_Ptr;
 304    function Source_Last       (S : SFI) return Source_Ptr;
 305    function Source_Text       (S : SFI) return Source_Buffer_Ptr;
 306    function Template          (S : SFI) return Source_File_Index;
 307    function Unit              (S : SFI) return Unit_Number_Type;
 308    function Time_Stamp        (S : SFI) return Time_Stamp_Type;
 309
 310    procedure Set_Keyword_Casing    (S : SFI; C : Casing_Type);
 311    procedure Set_Identifier_Casing (S : SFI; C : Casing_Type);
 312    procedure Set_License           (S : SFI; L : License_Type);
 313    procedure Set_Unit              (S : SFI; U : Unit_Number_Type);
 314
 315    function Last_Source_File return Source_File_Index;
 316    --  Index of last source file table entry
 317
 318    function Num_Source_Files return Nat;
 319    --  Number of source file table entries
 320
 321    procedure Initialize;
 322    --  Initialize internal tables
 323
 324    procedure Lock;
 325    --  Lock internal tables
 326
 327    procedure Unlock;
 328    --  Unlock internal tables
 329
 330    Main_Source_File : Source_File_Index := No_Source_File;
 331    --  This is set to the source file index of the main unit
 332
 333    -----------------------------
 334    -- Source_File_Index_Table --
 335    -----------------------------
 336
 337    --  The Get_Source_File_Index function is called very frequently. Earlier
 338    --  versions cached a single entry, but then reverted to a serial search,
 339    --  and this proved to be a significant source of inefficiency. To get
 340    --  around this, we use the following directly indexed array. The space
 341    --  of possible input values is a value of type Source_Ptr which is simply
 342    --  an Int value. The values in this space are allocated sequentially as
 343    --  new units are loaded.
 344
 345    --  The following table has an entry for each 4K range of possible
 346    --  Source_Ptr values. The value in the table is the lowest value
 347    --  Source_File_Index whose Source_Ptr range contains value in the
 348    --  range.
 349
 350    --  For example, the entry with index 4 in this table represents Source_Ptr
 351    --  values in the range 4*4096 .. 5*4096-1. The Source_File_Index value
 352    --  stored would be the lowest numbered source file with at least one byte
 353    --  in this range.
 354
 355    --  The algorithm used in Get_Source_File_Index is simply to access this
 356    --  table and then do a serial search starting at the given position. This
 357    --  will almost always terminate with one or two checks.
 358
 359    --  Note that this array is pretty large, but in most operating systems
 360    --  it will not be allocated in physical memory unless it is actually used.
 361
 362    Chunk_Power : constant := 12;
 363    Chunk_Size  : constant := 2 ** Chunk_Power;
 364    --  Change comments above if value changed. Note that Chunk_Size must
 365    --  be a power of 2 (to allow for efficient access to the table).
 366
 367    Source_File_Index_Table :
 368      array (Int range 0 .. Int'Last / Chunk_Size) of Source_File_Index;
 369
 370    procedure Set_Source_File_Index_Table (Xnew : Source_File_Index);
 371    --  Sets entries in the Source_File_Index_Table for the newly created
 372    --  Source_File table entry whose index is Xnew. The Source_First and
 373    --  Source_Last fields of this entry must be set before the call.
 374
 375    -----------------------
 376    -- Checksum Handling --
 377    -----------------------
 378
 379    --  As a source file is scanned, a checksum is computed by taking all the
 380    --  non-blank characters in the file, excluding comment characters, the
 381    --  minus-minus sequence starting a comment, and all control characters
 382    --  except ESC.
 383
 384    --  The checksum algorithm used is the standard CRC-32 algorithm, as
 385    --  implemented by System.CRC32, except that we do not bother with the
 386    --  final XOR with all 1 bits.
 387
 388    --  This algorithm ensures that the checksum includes all semantically
 389    --  significant aspects of the program represented by the source file,
 390    --  but is insensitive to layout, presence or contents of comments, wide
 391    --  character representation method, or casing conventions outside strings.
 392
 393    --  Scans.Checksum is initialized appropriately at the start of scanning
 394    --  a file, and copied into the Source_Checksum field of the file table
 395    --  entry when the end of file is encountered.
 396
 397    -------------------------------------
 398    -- Handling Generic Instantiations --
 399    -------------------------------------
 400
 401    --  As described in Sem_Ch12, a generic instantiation involves making a
 402    --  copy of the tree of the generic template. The source locations in
 403    --  this tree directly reference the source of the template. However it
 404    --  is also possible to find the location of the instantiation.
 405
 406    --  This is achieved as follows. When an instantiation occurs, a new entry
 407    --  is made in the source file table. This entry points to the same source
 408    --  text, i.e. the file that contains the instantiation, but has a distinct
 409    --  set of Source_Ptr index values. The separate range of Sloc values avoids
 410    --  confusion, and means that the Sloc values can still be used to uniquely
 411    --  identify the source file table entry. It is possible for both entries
 412    --  to point to the same text, because of the virtual origin pointers used
 413    --  in the source table.
 414
 415    --  The Instantiation field of this source file index entry, usually set
 416    --  to No_Source_File, instead contains the Sloc of the instantiation. In
 417    --  the case of nested instantiations, this Sloc may itself refer to an
 418    --  instantiation, so the complete chain can be traced.
 419
 420    --  Two routines are used to build these special entries in the source
 421    --  file table. Create_Instantiation_Source is first called to build
 422    --  the virtual source table entry for the instantiation, and then the
 423    --  Sloc values in the copy are adjusted using Adjust_Instantiation_Sloc.
 424    --  See child unit Sinput.L for details on these two routines.
 425
 426    -----------------
 427    -- Global Data --
 428    -----------------
 429
 430    Current_Source_File : Source_File_Index;
 431    --  Source_File table index of source file currently being scanned
 432
 433    Current_Source_Unit : Unit_Number_Type;
 434    --  Unit number of source file currently being scanned. The special value
 435    --  of No_Unit indicates that the configuration pragma file is currently
 436    --  being scanned (this has no entry in the unit table).
 437
 438    Source_gnat_adc : Source_File_Index := No_Source_File;
 439    --  This is set if a gnat.adc file is present to reference this file
 440
 441    Source : Source_Buffer_Ptr;
 442    --  Current source (copy of Source_File.Table (Current_Source_Unit).Source)
 443
 444    Internal_Source : aliased Source_Buffer (1 .. 81);
 445    --  This buffer is used internally in the compiler when the lexical analyzer
 446    --  is used to scan a string from within the compiler. The procedure is to
 447    --  establish Internal_Source_Ptr as the value of Source, set the string to
 448    --  be scanned, appropriately terminated, in this buffer, and set Scan_Ptr
 449    --  to point to the start of the buffer. It is a fatal error if the scanner
 450    --  signals an error while scanning a token in this internal buffer.
 451
 452    Internal_Source_Ptr : constant Source_Buffer_Ptr :=
 453                            Internal_Source'Unrestricted_Access;
 454    --  Pointer to internal source buffer
 455
 456    -----------------
 457    -- Subprograms --
 458    -----------------
 459
 460    procedure Backup_Line (P : in out Source_Ptr);
 461    --  Back up the argument pointer to the start of the previous line. On
 462    --  entry, P points to the start of a physical line in the source buffer.
 463    --  On return, P is updated to point to the start of the previous line.
 464    --  The caller has checked that a Line_Terminator character precedes P so
 465    --  that there definitely is a previous line in the source buffer.
 466
 467    procedure Build_Location_String (Loc : Source_Ptr);
 468    --  This function builds a string literal of the form "name:line", where
 469    --  name is the file name corresponding to Loc, and line is the line number.
 470    --  In the event that instantiations are involved, additional suffixes of
 471    --  the same form are appended after the separating string " instantiated at
 472    --  ". The returned string is appended to the Name_Buffer, terminated by
 473    --  ASCII.NUL, with Name_Length indicating the length not including the
 474    --  terminating Nul.
 475
 476    function Get_Column_Number (P : Source_Ptr) return Column_Number;
 477    --  The ones-origin column number of the specified Source_Ptr value is
 478    --  determined and returned. Tab characters if present are assumed to
 479    --  represent the standard 1,9,17.. spacing pattern.
 480
 481    function Get_Logical_Line_Number
 482      (P : Source_Ptr) return Logical_Line_Number;
 483    --  The line number of the specified source position is obtained by
 484    --  doing a binary search on the source positions in the lines table
 485    --  for the unit containing the given source position. The returned
 486    --  value is the logical line number, already adjusted for the effect
 487    --  of source reference pragmas. If P refers to the line of a source
 488    --  reference pragma itself, then No_Line is returned. If no source
 489    --  reference pragmas have been encountered, the value returned is
 490    --  the same as the physical line number.
 491
 492    function Get_Physical_Line_Number
 493      (P : Source_Ptr) return Physical_Line_Number;
 494    --  The line number of the specified source position is obtained by
 495    --  doing a binary search on the source positions in the lines table
 496    --  for the unit containing the given source position. The returned
 497    --  value is the physical line number in the source being compiled.
 498
 499    function Get_Source_File_Index (S : Source_Ptr) return Source_File_Index;
 500    --  Return file table index of file identified by given source pointer
 501    --  value. This call must always succeed, since any valid source pointer
 502    --  value belongs to some previously loaded source file.
 503
 504    function Instantiation_Depth (S : Source_Ptr) return Nat;
 505    --  Determine instantiation depth for given Sloc value. A value of
 506    --  zero means that the given Sloc is not in an instantiation.
 507
 508    function Line_Start (P : Source_Ptr) return Source_Ptr;
 509    --  Finds the source position of the start of the line containing the
 510    --  given source location.
 511
 512    function Line_Start
 513      (L : Physical_Line_Number;
 514       S : Source_File_Index) return Source_Ptr;
 515    --  Finds the source position of the start of the given line in the
 516    --  given source file, using a physical line number to identify the line.
 517
 518    function Num_Source_Lines (S : Source_File_Index) return Nat;
 519    --  Returns the number of source lines (this is equivalent to reading
 520    --  the value of Last_Source_Line, but returns Nat rather than a
 521    --  physical line number.
 522
 523    procedure Register_Source_Ref_Pragma
 524      (File_Name          : File_Name_Type;
 525       Stripped_File_Name : File_Name_Type;
 526       Mapped_Line        : Nat;
 527       Line_After_Pragma  : Physical_Line_Number);
 528    --  Register a source reference pragma, the parameter File_Name is the
 529    --  file name from the pragma, and Stripped_File_Name is this name with
 530    --  the directory information stripped. Both these parameters are set
 531    --  to No_Name if no file name parameter was given in the pragma.
 532    --  (which can only happen for the second and subsequent pragmas).
 533    --  Mapped_Line is the line number parameter from the pragma, and
 534    --  Line_After_Pragma is the physical line number of the line that
 535    --  follows the line containing the Source_Reference pragma.
 536
 537    function Original_Location (S : Source_Ptr) return Source_Ptr;
 538    --  Given a source pointer S, returns the corresponding source pointer
 539    --  value ignoring instantiation copies. For locations that do not
 540    --  correspond to instantiation copies of templates, the argument is
 541    --  returned unchanged. For locations that do correspond to copies of
 542    --  templates from instantiations, the location within the original
 543    --  template is returned. This is useful in canonicalizing locations.
 544
 545    function Instantiation_Location (S : Source_Ptr) return Source_Ptr;
 546    pragma Inline (Instantiation_Location);
 547    --  Given a source pointer S, returns the corresponding source pointer
 548    --  value of the instantiation if this location is within an instance.
 549    --  If S is not within an instance, then this returns No_Location.
 550
 551    function Top_Level_Location (S : Source_Ptr) return Source_Ptr;
 552    --  Given a source pointer S, returns the argument unchanged if it is
 553    --  not in an instantiation. If S is in an instantiation, then it returns
 554    --  the location of the top level instantiation, i.e. the outer level
 555    --  instantiation in the nested case.
 556
 557    function Physical_To_Logical
 558      (Line : Physical_Line_Number;
 559       S    : Source_File_Index) return Logical_Line_Number;
 560    --  Given a physical line number in source file whose source index is S,
 561    --  return the corresponding logical line number. If the physical line
 562    --  number is one containing a Source_Reference pragma, the result will
 563    --  be No_Line_Number.
 564
 565    procedure Skip_Line_Terminators
 566      (P        : in out Source_Ptr;
 567       Physical : out Boolean);
 568    --  On entry, P points to a line terminator that has been encountered,
 569    --  which is one of FF,LF,VT,CR or a wide character sequence whose value is
 570    --  in category Separator,Line or Separator,Paragraph. The purpose of this
 571    --  P points just past the character that was scanned. The purpose of this
 572    --  routine is to distinguish physical and logical line endings. A physical
 573    --  line ending is one of:
 574    --
 575    --     CR on its own (MAC System 7)
 576    --     LF on its own (Unix and unix-like systems)
 577    --     CR/LF (DOS, Windows)
 578    --     LF/CR (not used, but recognized in any case)
 579    --     Wide character in Separator,Line or Separator,Paragraph category
 580    --
 581    --  A logical line ending (that is not a physical line ending) is one of:
 582    --
 583    --     VT on its own
 584    --     FF on its own
 585    --
 586    --  On return, P is bumped past the line ending sequence (one of the above
 587    --  seven possibilities). Physical is set to True to indicate that a
 588    --  physical end of line was encountered, in which case this routine also
 589    --  makes sure that the lines table for the current source file has an
 590    --  appropriate entry for the start of the new physical line.
 591
 592    function Source_Offset (S : Source_Ptr) return Nat;
 593    --  Returns the zero-origin offset of the given source location from the
 594    --  start of its corresponding unit. This is used for creating canonical
 595    --  names in some situations.
 596
 597    procedure Write_Location (P : Source_Ptr);
 598    --  Writes out a string of the form fff:nn:cc, where fff, nn, cc are the
 599    --  file name, line number and column corresponding to the given source
 600    --  location. No_Location and Standard_Location appear as the strings
 601    --  <no location> and <standard location>. If the location is within an
 602    --  instantiation, then the instance location is appended, enclosed in
 603    --  square brackets (which can nest if necessary). Note that this routine
 604    --  is used only for internal compiler debugging output purposes (which
 605    --  is why the somewhat cryptic use of brackets is acceptable).
 606
 607    procedure wl (P : Source_Ptr);
 608    pragma Export (Ada, wl);
 609    --  Equivalent to Write_Location (P); Write_Eol; for calls from GDB
 610
 611    procedure Write_Time_Stamp (S : Source_File_Index);
 612    --  Writes time stamp of specified file in YY-MM-DD HH:MM.SS format
 613
 614    procedure Tree_Read;
 615    --  Initializes internal tables from current tree file using the relevant
 616    --  Table.Tree_Read routines.
 617
 618    procedure Tree_Write;
 619    --  Writes out internal tables to current tree file using the relevant
 620    --  Table.Tree_Write routines.
 621
 622 private
 623    pragma Inline (File_Name);
 624    pragma Inline (First_Mapped_Line);
 625    pragma Inline (Full_File_Name);
 626    pragma Inline (Identifier_Casing);
 627    pragma Inline (Instantiation);
 628    pragma Inline (Keyword_Casing);
 629    pragma Inline (Last_Source_Line);
 630    pragma Inline (Last_Source_File);
 631    pragma Inline (License);
 632    pragma Inline (Num_SRef_Pragmas);
 633    pragma Inline (Num_Source_Files);
 634    pragma Inline (Num_Source_Lines);
 635    pragma Inline (Reference_Name);
 636    pragma Inline (Set_Keyword_Casing);
 637    pragma Inline (Set_Identifier_Casing);
 638    pragma Inline (Source_First);
 639    pragma Inline (Source_Last);
 640    pragma Inline (Source_Text);
 641    pragma Inline (Template);
 642    pragma Inline (Time_Stamp);
 643
 644    -------------------------
 645    -- Source_Lines Tables --
 646    -------------------------
 647
 648    type Lines_Table_Type is
 649      array (Physical_Line_Number) of Source_Ptr;
 650    --  Type used for lines table. The entries are indexed by physical line
 651    --  numbers. The values are the starting Source_Ptr values for the start
 652    --  of the corresponding physical line. Note that we make this a bogus
 653    --  big array, sized as required, so that we avoid the use of fat pointers.
 654
 655    type Lines_Table_Ptr is access all Lines_Table_Type;
 656    --  Type used for pointers to line tables
 657
 658    type Logical_Lines_Table_Type is
 659      array (Physical_Line_Number) of Logical_Line_Number;
 660    --  Type used for logical lines table. This table is used if a source
 661    --  reference pragma is present. It is indexed by physical line numbers,
 662    --  and contains the corresponding logical line numbers. An entry that
 663    --  corresponds to a source reference pragma is set to No_Line_Number.
 664    --  Note that we make this a bogus big array, sized as required, so that
 665    --  we avoid the use of fat pointers.
 666
 667    type Logical_Lines_Table_Ptr is access all Logical_Lines_Table_Type;
 668    --  Type used for pointers to logical line tables
 669
 670    -----------------------
 671    -- Source_File Table --
 672    -----------------------
 673
 674    --  See earlier descriptions for meanings of public fields
 675
 676    type Source_File_Record is record
 677       File_Name         : File_Name_Type;
 678       Reference_Name    : File_Name_Type;
 679       Debug_Source_Name : File_Name_Type;
 680       Full_Debug_Name   : File_Name_Type;
 681       Full_File_Name    : File_Name_Type;
 682       Full_Ref_Name     : File_Name_Type;
 683       Num_SRef_Pragmas  : Nat;
 684       First_Mapped_Line : Logical_Line_Number;
 685       Source_Text       : Source_Buffer_Ptr;
 686       Source_First      : Source_Ptr;
 687       Source_Last       : Source_Ptr;
 688       Source_Checksum   : Word;
 689       Last_Source_Line  : Physical_Line_Number;
 690       Instantiation     : Source_Ptr;
 691       Template          : Source_File_Index;
 692       Unit              : Unit_Number_Type;
 693       Time_Stamp        : Time_Stamp_Type;
 694       File_Type         : Type_Of_File;
 695       Inlined_Body      : Boolean;
 696       License           : License_Type;
 697       Keyword_Casing    : Casing_Type;
 698       Identifier_Casing : Casing_Type;
 699
 700       --  The following fields are for internal use only (i.e. only in the
 701       --  body of Sinput or its children, with no direct access by clients).
 702
 703       Sloc_Adjust : Source_Ptr;
 704       --  A value to be added to Sloc values for this file to reference the
 705       --  corresponding lines table. This is zero for the non-instantiation
 706       --  case, and set so that the addition references the ultimate template
 707       --  for the instantiation case. See Sinput-L for further details.
 708
 709       Lines_Table : Lines_Table_Ptr;
 710       --  Pointer to lines table for this source. Updated as additional
 711       --  lines are accessed using the Skip_Line_Terminators procedure.
 712       --  Note: the lines table for an instantiation entry refers to the
 713       --  original line numbers of the template see Sinput-L for details.
 714
 715       Logical_Lines_Table : Logical_Lines_Table_Ptr;
 716       --  Pointer to logical lines table for this source. Non-null only if
 717       --  a source reference pragma has been processed. Updated as lines
 718       --  are accessed using the Skip_Line_Terminators procedure.
 719
 720       Lines_Table_Max : Physical_Line_Number;
 721       --  Maximum subscript values for currently allocated Lines_Table
 722       --  and (if present) the allocated Logical_Lines_Table. The value
 723       --  Max_Source_Line gives the maximum used value, this gives the
 724       --  maximum allocated value.
 725
 726    end record;
 727
 728    --  The following representation clause ensures that the above record
 729    --  has no holes. We do this so that when instances of this record are
 730    --  written by Tree_Gen, we do not write uninitialized values to the file.
 731
 732    AS : constant Pos := Standard'Address_Size;
 733
 734    for Source_File_Record use record
 735       File_Name           at  0 range 0 .. 31;
 736       Reference_Name      at  4 range 0 .. 31;
 737       Debug_Source_Name   at  8 range 0 .. 31;
 738       Full_Debug_Name     at 12 range 0 .. 31;
 739       Full_File_Name      at 16 range 0 .. 31;
 740       Full_Ref_Name       at 20 range 0 .. 31;
 741       Num_SRef_Pragmas    at 24 range 0 .. 31;
 742       First_Mapped_Line   at 28 range 0 .. 31;
 743       Source_First        at 32 range 0 .. 31;
 744       Source_Last         at 36 range 0 .. 31;
 745       Source_Checksum     at 40 range 0 .. 31;
 746       Last_Source_Line    at 44 range 0 .. 31;
 747       Instantiation       at 48 range 0 .. 31;
 748       Template            at 52 range 0 .. 31;
 749       Unit                at 56 range 0 .. 31;
 750       Time_Stamp          at 60 range 0 .. 8 * Time_Stamp_Length - 1;
 751       File_Type           at 74 range 0 .. 7;
 752       Inlined_Body        at 75 range 0 .. 7;
 753       License             at 76 range 0 .. 7;
 754       Keyword_Casing      at 77 range 0 .. 7;
 755       Identifier_Casing   at 78 range 0 .. 15;
 756       Sloc_Adjust         at 80 range 0 .. 31;
 757       Lines_Table_Max     at 84 range 0 .. 31;
 758
 759       --  The following fields are pointers, so we have to specialize their
 760       --  lengths using pointer size, obtained above as Standard'Address_Size.
 761
 762       Source_Text         at 88 range 0      .. AS - 1;
 763       Lines_Table         at 88 range AS     .. AS * 2 - 1;
 764       Logical_Lines_Table at 88 range AS * 2 .. AS * 3 - 1;
 765    end record;
 766
 767    for Source_File_Record'Size use 88 * 8 + AS * 3;
 768    --  This ensures that we did not leave out any fields
 769
 770    package Source_File is new Table.Table (
 771      Table_Component_Type => Source_File_Record,
 772      Table_Index_Type     => Source_File_Index,
 773      Table_Low_Bound      => 1,
 774      Table_Initial        => Alloc.Source_File_Initial,
 775      Table_Increment      => Alloc.Source_File_Increment,
 776      Table_Name           => "Source_File");
 777
 778    -----------------
 779    -- Subprograms --
 780    -----------------
 781
 782    procedure Alloc_Line_Tables
 783      (S       : in out Source_File_Record;
 784       New_Max : Nat);
 785    --  Allocate or reallocate the lines table for the given source file so
 786    --  that it can accommodate at least New_Max lines. Also allocates or
 787    --  reallocates logical lines table if source ref pragmas are present.
 788
 789    procedure Add_Line_Tables_Entry
 790      (S : in out Source_File_Record;
 791       P : Source_Ptr);
 792    --  Increment line table size by one (reallocating the lines table if
 793    --  needed) and set the new entry to contain the value P. Also bumps
 794    --  the Source_Line_Count field. If source reference pragmas are
 795    --  present, also increments logical lines table size by one, and
 796    --  sets new entry.
 797
 798    procedure Trim_Lines_Table (S : Source_File_Index);
 799    --  Set lines table size for entry S in the source file table to
 800    --  correspond to the current value of Num_Source_Lines, releasing
 801    --  any unused storage. This is used by Sinput.L and Sinput.D.
 802
 803 end Sinput;