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-2023, 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 the input routines used for reading the
  27 --  input source file. The actual I/O routines are in OS_Interface,
  28 --  with this module containing only the system independent processing.
  29
  30 --  General Note: throughout the compiler, we use the term line or source
  31 --  line to refer to a physical line in the source, terminated by the end of
  32 --  physical line sequence.
  33
  34 --  There are two distinct concepts of line terminator in GNAT
  35
  36 --    A logical line terminator is what corresponds to the "end of a line" as
  37 --    described in RM 2.2 (13). Any of the characters FF, LF, CR or VT or any
  38 --    wide character that is a Line or Paragraph Separator acts as an end of
  39 --    logical line in this sense, and it is essentially irrelevant whether one
  40 --    or more appears in sequence (since if a sequence of such characters is
  41 --    regarded as separate ends of line, then the intervening logical lines
  42 --    are null in any case).
  43
  44 --    A physical line terminator is a sequence of format effectors that is
  45 --    treated as ending a physical line. Physical lines have no Ada semantic
  46 --    significance, but they are significant for error reporting purposes,
  47 --    since errors are identified by line and column location.
  48
  49 --  In GNAT, a physical line is ended by any of the sequences LF, CR/LF, or
  50 --  CR. LF is used in typical Unix systems, CR/LF in DOS systems, and CR
  51 --  alone in System 7. In addition, we recognize any of these sequences in
  52 --  any of the operating systems, for better behavior in treating foreign
  53 --  files (e.g. a Unix file with LF terminators transferred to a DOS system).
  54 --  Finally, wide character codes in categories Separator, Line and Separator,
  55 --  Paragraph are considered to be physical line terminators.
  56
  57 with Alloc;
  58 with Casing; use Casing;
  59 with Namet;  use Namet;
  60 with System;
  61 with Table;
  62 with Types;  use Types;
  63
  64 package Sinput is
  65
  66    type Type_Of_File is (
  67    --  Indicates type of file being read
  68
  69       Src,
  70       --  Normal Ada source file
  71
  72       Config,
  73       --  Configuration pragma file
  74
  75       Def,
  76       --  Preprocessing definition file
  77
  78       Preproc);
  79       --  Source file with preprocessing commands to be preprocessed
  80
  81    type Instance_Id is new Nat;
  82    No_Instance_Id : constant Instance_Id;
  83
  84    ----------------------------
  85    -- Source License Control --
  86    ----------------------------
  87
  88    --  The following type indicates the license state of a source if it
  89    --  is known.
  90
  91    type License_Type is
  92      (Unknown,
  93       --  Licensing status of this source unit is unknown
  94
  95       Restricted,
  96       --  This is a non-GPL'ed unit that is restricted from depending
  97       --  on GPL'ed units (e.g. proprietary code is in this category)
  98
  99       GPL,
 100       --  This file is licensed under the unmodified GPL. It is not allowed
 101       --  to depend on Non_GPL units, and Non_GPL units may not depend on
 102       --  this source unit.
 103
 104       Modified_GPL,
 105       --  This file is licensed under the GNAT modified GPL (see header of
 106       --  This file for wording of the modification). It may depend on other
 107       --  Modified_GPL units or on unrestricted units.
 108
 109       Unrestricted);
 110       --  The license on this file is permitted to depend on any other
 111       --  units, or have other units depend on it, without violating the
 112       --  license of this unit. Examples are public domain units, and
 113       --  units defined in the RM).
 114
 115    --  The above license status is checked when the appropriate check is
 116    --  activated and one source depends on another, and the licensing state
 117    --  of both files is known:
 118
 119    --  The prohibited combinations are:
 120
 121    --    Restricted file may not depend on GPL file
 122
 123    --    GPL file may not depend on Restricted file
 124
 125    --    Modified GPL file may not depend on Restricted file
 126    --    Modified_GPL file may not depend on GPL file
 127
 128    --  The reason for the last restriction here is that a client depending
 129    --  on a modified GPL file must be sure that the license condition is
 130    --  correct considered transitively.
 131
 132    --  The licensing status is determined either by the presence of a
 133    --  specific pragma License, or by scanning the header for a predefined
 134    --  statement, or any file if compiling in -gnatg mode.
 135
 136    -----------------------
 137    -- Source File Table --
 138    -----------------------
 139
 140    --  The source file table has an entry for each source file read in for
 141    --  this run of the compiler. This table is (default) initialized when
 142    --  the compiler is loaded, and simply accumulates entries as compilation
 143    --  proceeds and various routines in Sinput and its child packages are
 144    --  called to load required source files.
 145
 146    --  Virtual entries are also created for generic templates when they are
 147    --  instantiated, as described in a separate section later on.
 148
 149    --  In the case where there are multiple main units (e.g. in the case of
 150    --  the cross-reference tool), this table is not reset between these units,
 151    --  so that a given source file is only read once if it is used by two
 152    --  separate main units.
 153
 154    --  The entries in the table are accessed using a Source_File_Index that
 155    --  ranges from 1 to Last_Source_File. Each entry has the following fields.
 156
 157    --  Note: fields marked read-only are set by Sinput or one of its child
 158    --  packages when a source file table entry is created, and cannot be
 159    --  subsequently modified, or alternatively are set only by very special
 160    --  circumstances, documented in the comments.
 161
 162    --  File_Name : File_Name_Type (read-only)
 163    --    Name of the source file (simple name with no directory information)
 164
 165    --  Full_File_Name : File_Name_Type (read-only)
 166    --    Full file name (full name with directory info), used for generation
 167    --    of error messages, etc.
 168
 169    --  File_Type : Type_Of_File (read-only)
 170    --    Indicates type of file (source file, configuration pragmas file,
 171    --    preprocessor definition file, preprocessor input file).
 172
 173    --  Reference_Name : File_Name_Type (read-only)
 174    --    Name to be used for source file references in error messages where
 175    --    only the simple name of the file is required. Identical to File_Name
 176    --    unless pragma Source_Reference is used to change it. Only processing
 177    --    for the Source_Reference pragma circuit may set this field.
 178
 179    --  Full_Ref_Name : File_Name_Type (read-only)
 180    --    Name to be used for source file references in error messages where
 181    --    the full name of the file is required. Identical to Full_File_Name
 182    --    unless pragma Source_Reference is used to change it. Only processing
 183    --    for the Source_Reference pragma may set this field.
 184
 185    --  Debug_Source_Name : File_Name_Type (read-only)
 186    --    Name to be used for source file references in debugging information
 187    --    where only the simple name of the file is required. Identical to
 188    --    Reference_Name unless the -gnatD (debug source file) switch is used.
 189    --    Only processing in Sprint that generates this file is permitted to
 190    --    set this field.
 191
 192    --  Full_Debug_Name : File_Name_Type (read-only)
 193    --    Name to be used for source file references in debugging information
 194    --    where the full name of the file is required. This is identical to
 195    --    Full_Ref_Name unless the -gnatD (debug source file) switch is used.
 196    --    Only processing in Sprint that generates this file is permitted to
 197    --    set this field.
 198
 199    --  Instance : Instance_Id (read-only)
 200    --    For entries corresponding to a generic instantiation, unique
 201    --    identifier denoting the full chain of nested instantiations. Set to
 202    --    No_Instance_Id for the case of a normal, non-instantiation entry.
 203    --    See below for details on the handling of generic instantiations.
 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. Every source file has a distinct set of
 218    --    nonoverlapping bounds, so it is possible to determine which
 219    --    file is referenced from a given subscript (Source_Ptr) value.
 220
 221    --  Source_First : Source_Ptr; (read-only)
 222    --    This is always equal to Source_Text'First, except during
 223    --    construction of a debug output file (*.dg), when Source_Text = null,
 224    --    and Source_First is the size so far. Likewise for Last.
 225
 226    --  Source_Last : Source_Ptr; (read-only)
 227    --    Same idea as Source_Last, but for Last
 228
 229    --  Time_Stamp : Time_Stamp_Type; (read-only)
 230    --    Time stamp of the source file
 231
 232    --  Source_Checksum : Word;
 233    --    Computed checksum for contents of source file. See separate section
 234    --    later on in this spec for a description of the checksum algorithm.
 235
 236    --  Last_Source_Line : Physical_Line_Number;
 237    --    Physical line number of last source line. While a file is being
 238    --    read, this refers to the last line scanned. Once a file has been
 239    --    completely scanned, it is the number of the last line in the file,
 240    --    and hence also gives the number of source lines in the file.
 241
 242    --  Keyword_Casing : Casing_Type;
 243    --    Casing style used in file for keyword casing. This is initialized
 244    --    to Unknown, and then set from the first occurrence of a keyword.
 245    --    This value is used only for formatting of error messages.
 246
 247    --  Identifier_Casing : Casing_Type;
 248    --    Casing style used in file for identifier casing. This is initialized
 249    --    to Unknown, and then set from an identifier in the program as soon as
 250    --    one is found whose casing is sufficiently clear to make a decision.
 251    --    This value is used for formatting of error messages, and also is used
 252    --    in the detection of keywords misused as identifiers.
 253
 254    --  Inlined_Call : Source_Ptr;
 255    --    Source file location of the subprogram call if this source file entry
 256    --    represents an inlined body or an inherited pragma. Set to No_Location
 257    --    otherwise. This field is read-only for clients.
 258
 259    --  Inlined_Body : Boolean;
 260    --    This can only be set True if Instantiation has a value other than
 261    --    No_Location. If true it indicates that the instantiation is actually
 262    --    an instance of an inlined body.
 263
 264    --  Inherited_Pragma : Boolean;
 265    --    This can only be set True if Instantiation has a value other than
 266    --    No_Location. If true it indicates that the instantiation is actually
 267    --    an inherited class-wide pre- or postcondition.
 268
 269    --  Template : Source_File_Index; (read-only)
 270    --    Source file index of the source file containing the template if this
 271    --    is a generic instantiation. Set to No_Source_File for the normal case
 272    --    of a non-instantiation entry. See Sinput-L for details.
 273
 274    --  Unit : Unit_Number_Type;
 275    --    Identifies the unit contained in this source file. Set by
 276    --    Initialize_Scanner, must not be subsequently altered.
 277
 278    --  The source file table is accessed by clients using the following
 279    --  subprogram interface:
 280
 281    subtype SFI is Source_File_Index;
 282
 283    System_Source_File_Index : SFI;
 284    --  The file system.ads is always read by the compiler to determine the
 285    --  settings of the target parameters in the private part of System. This
 286    --  variable records the source file index of system.ads. Typically this
 287    --  will be 1 since system.ads is read first.
 288
 289    function Debug_Source_Name (S : SFI) return File_Name_Type;
 290    --  WARNING: There is a matching C declaration of this subprogram in fe.h
 291
 292    function File_Name         (S : SFI) return File_Name_Type;
 293    function File_Type         (S : SFI) return Type_Of_File;
 294    function First_Mapped_Line (S : SFI) return Logical_Line_Number;
 295    function Full_Debug_Name   (S : SFI) return File_Name_Type;
 296    function Full_File_Name    (S : SFI) return File_Name_Type;
 297    function Full_Ref_Name     (S : SFI) return File_Name_Type;
 298    function Identifier_Casing (S : SFI) return Casing_Type;
 299    function Inlined_Body      (S : SFI) return Boolean;
 300    function Inherited_Pragma  (S : SFI) return Boolean;
 301    function Inlined_Call      (S : SFI) return Source_Ptr;
 302    function Instance          (S : SFI) return Instance_Id;
 303    function Keyword_Casing    (S : SFI) return Casing_Type;
 304    function Last_Source_Line  (S : SFI) return Physical_Line_Number;
 305    function License           (S : SFI) return License_Type;
 306    function Num_SRef_Pragmas  (S : SFI) return Nat;
 307    function Reference_Name    (S : SFI) return File_Name_Type;
 308    function Source_Checksum   (S : SFI) return Word;
 309    function Source_First      (S : SFI) return Source_Ptr;
 310    function Source_Last       (S : SFI) return Source_Ptr;
 311    function Source_Text       (S : SFI) return Source_Buffer_Ptr;
 312    function Template          (S : SFI) return Source_File_Index;
 313    function Unit              (S : SFI) return Unit_Number_Type;
 314    function Time_Stamp        (S : SFI) return Time_Stamp_Type;
 315
 316    procedure Set_Keyword_Casing    (S : SFI; C : Casing_Type);
 317    procedure Set_Identifier_Casing (S : SFI; C : Casing_Type);
 318    procedure Set_License           (S : SFI; L : License_Type);
 319    procedure Set_Unit              (S : SFI; U : Unit_Number_Type);
 320
 321    function Last_Source_File return Source_File_Index;
 322    --  Index of last source file table entry
 323
 324    function Num_Source_Files return Nat;
 325    --  Number of source file table entries
 326
 327    procedure Initialize;
 328    --  Initialize internal tables
 329
 330    procedure Lock;
 331    --  Lock internal tables
 332
 333    procedure Unlock;
 334    --  Unlock internal tables
 335
 336    Main_Source_File : Source_File_Index := No_Source_File;
 337    --  This is set to the source file index of the main unit
 338
 339    -----------------------
 340    -- Checksum Handling --
 341    -----------------------
 342
 343    --  As a source file is scanned, a checksum is computed by taking all the
 344    --  non-blank characters in the file, excluding comment characters, the
 345    --  minus-minus sequence starting a comment, and all control characters
 346    --  except ESC.
 347
 348    --  The checksum algorithm used is the standard CRC-32 algorithm, as
 349    --  implemented by System.CRC32, except that we do not bother with the
 350    --  final XOR with all 1 bits.
 351
 352    --  This algorithm ensures that the checksum includes all semantically
 353    --  significant aspects of the program represented by the source file,
 354    --  but is insensitive to layout, presence or contents of comments, wide
 355    --  character representation method, or casing conventions outside strings.
 356
 357    --  Scans.Checksum is initialized appropriately at the start of scanning
 358    --  a file, and copied into the Source_Checksum field of the file table
 359    --  entry when the end of file is encountered.
 360
 361    -------------------------------------
 362    -- Handling Generic Instantiations --
 363    -------------------------------------
 364
 365    --  As described in Sem_Ch12, a generic instantiation involves making a
 366    --  copy of the tree of the generic template. The source locations in
 367    --  this tree directly reference the source of the template. However, it
 368    --  is also possible to find the location of the instantiation.
 369
 370    --  This is achieved as follows. When an instantiation occurs, a new entry
 371    --  is made in the source file table. The Source_Text of the instantiation
 372    --  points to the same Source_Buffer as the Source_Text of the template, but
 373    --  with different bounds. The separate range of Sloc values avoids
 374    --  confusion, and means that the Sloc values can still be used to uniquely
 375    --  identify the source file table entry. See Set_Dope below for the
 376    --  low-level trickery that allows two different pointers to point at the
 377    --  same array, but with different bounds.
 378
 379    --  The Instantiation_Id field of this source file index entry, set
 380    --  to No_Instance_Id for normal entries, instead contains a value that
 381    --  uniquely identifies a particular instantiation, and the associated
 382    --  entry in the Instances table. The source location of the instantiation
 383    --  can be retrieved using function Instantiation below. In the case of
 384    --  nested instantiations, the Instances table can be used to trace the
 385    --  complete chain of nested instantiations.
 386
 387    --  Two routines are used to build the special instance entries in the
 388    --  source file table. Create_Instantiation_Source is first called to build
 389    --  the virtual source table entry for the instantiation, and then the
 390    --  Sloc values in the copy are adjusted using Adjust_Instantiation_Sloc.
 391    --  See child unit Sinput.L for details on these two routines.
 392
 393    generic
 394       with procedure Process (Id : Instance_Id; Inst_Sloc : Source_Ptr);
 395    procedure Iterate_On_Instances;
 396    --  Execute Process for each entry in the instance table
 397
 398    function Instantiation (S : SFI) return Source_Ptr;
 399    --  For a source file entry that represents an inlined body, source location
 400    --  of the inlined call. For a source file entry that represents an
 401    --  inherited pragma, source location of the declaration to which the
 402    --  overriding subprogram for the inherited pragma is attached. Otherwise,
 403    --  for a source file entry that represents a generic instantiation, source
 404    --  location of the instantiation. Returns No_Location in all other cases.
 405
 406    -----------------
 407    -- Global Data --
 408    -----------------
 409
 410    Current_Source_File : Source_File_Index := No_Source_File;
 411    --  Source_File table index of source file currently being scanned.
 412
 413    Current_Source_Unit : Unit_Number_Type := No_Unit;
 414    --  Unit number of source file currently being scanned. Initialized to
 415    --  No_Unit for pre-processing and the configuration pragma file scanning,
 416    --  since both stages have no corresponding entry in the unit table.
 417
 418    Source_gnat_adc : Source_File_Index := No_Source_File;
 419    --  This is set if a gnat.adc file is present to reference this file
 420
 421    Source : Source_Buffer_Ptr;
 422    --  Current source (copy of Source_File.Table (Current_Source_Unit).Source)
 423
 424    -----------------------------------------
 425    -- Handling of Source Line Terminators --
 426    -----------------------------------------
 427
 428    --  In this section we discuss in detail the issue of terminators used to
 429    --  terminate source lines. The RM says that one or more format effectors
 430    --  (other than horizontal tab) end a source line, and defines the set of
 431    --  such format effectors, but does not talk about exactly how they are
 432    --  represented in the source program (since in general the RM is not in
 433    --  the business of specifying source program formats).
 434
 435    --  The type Types.Line_Terminator is defined as a subtype of Character
 436    --  that includes CR/LF/VT/FF. The most common line enders in practice
 437    --  are CR (some MAC systems), LF (Unix systems), and CR/LF (DOS/Windows
 438    --  systems). Any of these sequences is recognized as ending a physical
 439    --  source line, and if multiple such terminators appear (e.g. LF/LF),
 440    --  then we consider we have an extra blank line.
 441
 442    --  VT and FF are recognized as terminating source lines, but they are
 443    --  considered to end a logical line instead of a physical line, so that
 444    --  the line numbering ignores such terminators. The use of VT and FF is
 445    --  mandated by the standard, and correctly handled in a conforming manner
 446    --  by GNAT, but their use is not recommended.
 447
 448    --  In addition to the set of characters defined by the type in Types, in
 449    --  wide character encoding, then the codes returning True for a call to
 450    --  System.UTF_32.Is_UTF_32_Line_Terminator are also recognized as ending a
 451    --  source line. This includes the standard codes defined above in addition
 452    --  to NEL (NEXT LINE), LINE SEPARATOR and PARAGRAPH SEPARATOR. Again, as in
 453    --  the case of VT and FF, the standard requires we recognize these as line
 454    --  terminators, but we consider them to be logical line terminators. The
 455    --  only physical line terminators recognized are the standard ones (CR,
 456    --  LF, or CR/LF).
 457
 458    --  However, we do not recognize the NEL (16#85#) character as having the
 459    --  significance of an end of line character when operating in normal 8-bit
 460    --  Latin-n input mode for the compiler. Instead the rule in this mode is
 461    --  that all upper half control codes (16#80# .. 16#9F#) are illegal if they
 462    --  occur in program text, and are ignored if they appear in comments.
 463
 464    --  First, note that this behavior is fully conforming with the standard.
 465    --  The standard has nothing whatever to say about source representation
 466    --  and implementations are completely free to make there own rules. In
 467    --  this case, in 8-bit mode, GNAT decides that the 16#0085# character is
 468    --  not a representation of the NEL character, even though it looks like it.
 469    --  If you have NEL's in your program, which you expect to be treated as
 470    --  end of line characters, you must use a wide character encoding such as
 471    --  UTF-8 for this code to be recognized.
 472
 473    --  Second, an explanation of why we take this slightly surprising choice.
 474    --  We have never encountered anyone actually using the NEL character to
 475    --  end lines. One user raised the issue as a result of some experiments,
 476    --  but no one has ever submitted a program encoded this way, in any of
 477    --  the possible encodings. It seems that even when using wide character
 478    --  codes extensively, the normal approach is to use standard line enders
 479    --  (LF or CR/LF). So the failure to recognize NEL in this mode seems to
 480    --  have no practical downside.
 481
 482    --  Moreover, what we have seen in a significant number of programs from
 483    --  multiple sources is the practice of writing all program text in lower
 484    --  half (ASCII) form, but using UTF-8 encoded wide characters freely in
 485    --  comments, where the comments are terminated by normal line endings
 486    --  (LF or CR/LF). The comments do not contain NEL codes, but they can and
 487    --  do contain other UTF-8 encoding sequences where one of the bytes is the
 488    --  NEL code. Now such programs can of course be compiled in UTF-8 mode,
 489    --  but in practice they also compile fine in standard 8-bit mode without
 490    --  specifying a character encoding. Since this is common practice, it would
 491    --  be a significant upwards incompatibility to recognize NEL in 8-bit mode.
 492
 493    -----------------
 494    -- Subprograms --
 495    -----------------
 496
 497    procedure Backup_Line (P : in out Source_Ptr);
 498    --  Back up the argument pointer to the start of the previous line. On
 499    --  entry, P points to the start of a physical line in the source buffer.
 500    --  On return, P is updated to point to the start of the previous line.
 501    --  The caller has checked that a Line_Terminator character precedes P so
 502    --  that there definitely is a previous line in the source buffer.
 503
 504    procedure Build_Location_String
 505      (Buf : in out Bounded_String;
 506       Loc : Source_Ptr);
 507    --  This function builds a string literal of the form "name:line", where
 508    --  name is the file name corresponding to Loc, and line is the line number.
 509    --  If instantiations are involved, additional suffixes of the same form are
 510    --  appended after the separating string " instantiated at ". The returned
 511    --  string is appended to Buf.
 512
 513    function Build_Location_String (Loc : Source_Ptr) return String;
 514    --  Functional form returning a String
 515
 516    procedure Check_For_BOM;
 517    --  Check if the current source starts with a BOM. Scan_Ptr needs to be at
 518    --  the start of the current source. If the current source starts with a
 519    --  recognized BOM, then some flags such as Wide_Character_Encoding_Method
 520    --  are set accordingly, and the Scan_Ptr on return points past this BOM.
 521    --  An error message is output and Unrecoverable_Error raised if an
 522    --  unrecognized BOM is detected. The call has no effect if no BOM is found.
 523
 524    function Get_Column_Number (P : Source_Ptr) return Column_Number;
 525    --  The ones-origin column number of the specified Source_Ptr value is
 526    --  determined and returned. Tab characters if present are assumed to
 527    --  represent the standard 1,9,17.. spacing pattern.
 528
 529    --  WARNING: There is a matching C declaration of this subprogram in fe.h
 530
 531    function Get_Logical_Line_Number
 532      (P : Source_Ptr) return Logical_Line_Number;
 533    --  The line number of the specified source position is obtained by
 534    --  doing a binary search on the source positions in the lines table
 535    --  for the unit containing the given source position. The returned
 536    --  value is the logical line number, already adjusted for the effect
 537    --  of source reference pragmas. If P refers to the line of a source
 538    --  reference pragma itself, then No_Line is returned. If no source
 539    --  reference pragmas have been encountered, the value returned is
 540    --  the same as the physical line number.
 541
 542    --  WARNING: There is a matching C declaration of this subprogram in fe.h
 543
 544    function Get_Logical_Line_Number_Img
 545      (P : Source_Ptr) return String;
 546    --  Same as above function, but returns the line number as a string of
 547    --  decimal digits, with no leading space. Destroys Name_Buffer.
 548
 549    function Get_Physical_Line_Number
 550      (P : Source_Ptr) return Physical_Line_Number;
 551    --  The line number of the specified source position is obtained by
 552    --  doing a binary search on the source positions in the lines table
 553    --  for the unit containing the given source position. The returned
 554    --  value is the physical line number in the source being compiled.
 555
 556    function Get_Source_File_Index (S : Source_Ptr) return Source_File_Index;
 557    pragma Inline (Get_Source_File_Index);
 558    --  Return file table index of file identified by given source pointer
 559    --  value. This call must always succeed, since any valid source pointer
 560    --  value belongs to some previously loaded source file.
 561
 562    --  WARNING: There is a matching C declaration of this subprogram in fe.h
 563
 564    function Instantiation_Depth (S : Source_Ptr) return Nat;
 565    --  Determine instantiation depth for given Sloc value. A value of
 566    --  zero means that the given Sloc is not in an instantiation.
 567
 568    function Line_Start (P : Source_Ptr) return Source_Ptr;
 569    --  Finds the source position of the start of the line containing the
 570    --  given source location.
 571
 572    function Line_Start
 573      (L : Physical_Line_Number;
 574       S : Source_File_Index) return Source_Ptr;
 575    --  Finds the source position of the start of the given line in the
 576    --  given source file, using a physical line number to identify the line.
 577
 578    function Num_Source_Lines (S : Source_File_Index) return Nat;
 579    --  Returns the number of source lines (this is equivalent to reading
 580    --  the value of Last_Source_Line, but returns Nat rather than a
 581    --  physical line number).
 582
 583    procedure Register_Source_Ref_Pragma
 584      (File_Name          : File_Name_Type;
 585       Stripped_File_Name : File_Name_Type;
 586       Mapped_Line        : Nat;
 587       Line_After_Pragma  : Physical_Line_Number);
 588    --  Register a source reference pragma, the parameter File_Name is the
 589    --  file name from the pragma, and Stripped_File_Name is this name with
 590    --  the directory information stripped. Both these parameters are set
 591    --  to No_Name if no file name parameter was given in the pragma.
 592    --  (which can only happen for the second and subsequent pragmas).
 593    --  Mapped_Line is the line number parameter from the pragma, and
 594    --  Line_After_Pragma is the physical line number of the line that
 595    --  follows the line containing the Source_Reference pragma.
 596
 597    function Original_Location (S : Source_Ptr) return Source_Ptr;
 598    --  Given a source pointer S, returns the corresponding source pointer
 599    --  value ignoring instantiation copies. For locations that do not
 600    --  correspond to instantiation copies of templates, the argument is
 601    --  returned unchanged. For locations that do correspond to copies of
 602    --  templates from instantiations, the location within the original
 603    --  template is returned. This is useful in canonicalizing locations.
 604
 605    function Instantiation_Location (S : Source_Ptr) return Source_Ptr;
 606    pragma Inline (Instantiation_Location);
 607    --  Given a source pointer S, returns the corresponding source pointer
 608    --  value of the instantiation if this location is within an instance.
 609    --  If S is not within an instance, then this returns No_Location.
 610
 611    function Comes_From_Inlined_Body (S : Source_Ptr) return Boolean;
 612    pragma Inline (Comes_From_Inlined_Body);
 613    --  Given a source pointer S, returns whether it comes from an inlined body.
 614    --  This allows distinguishing these source pointers from those that come
 615    --  from instantiation of generics, since Instantiation_Location returns a
 616    --  valid location in both cases.
 617
 618    function Comes_From_Inherited_Pragma (S : Source_Ptr) return Boolean;
 619    pragma Inline (Comes_From_Inherited_Pragma);
 620    --  Given a source pointer S, returns whether it comes from an inherited
 621    --  pragma. This allows distinguishing these source pointers from those
 622    --  that come from instantiation of generics, since Instantiation_Location
 623    --  returns a valid location in both cases.
 624
 625    function Top_Level_Location (S : Source_Ptr) return Source_Ptr;
 626    --  Given a source pointer S, returns the argument unchanged if it is
 627    --  not in an instantiation. If S is in an instantiation, then it returns
 628    --  the location of the top level instantiation, i.e. the outer level
 629    --  instantiation in the nested case.
 630
 631    function Physical_To_Logical
 632      (Line : Physical_Line_Number;
 633       S    : Source_File_Index) return Logical_Line_Number;
 634    --  Given a physical line number in source file whose source index is S,
 635    --  return the corresponding logical line number. If the physical line
 636    --  number is one containing a Source_Reference pragma, the result will
 637    --  be No_Line_Number.
 638
 639    procedure Skip_Line_Terminators
 640      (P        : in out Source_Ptr;
 641       Physical : out Boolean);
 642    --  On entry, P points to a line terminator that has been encountered,
 643    --  which is one of FF,LF,VT,CR or a wide character sequence whose value is
 644    --  in category Separator,Line or Separator,Paragraph. P points just past
 645    --  the character that was scanned. The purpose of this routine is to
 646    --  distinguish physical and logical line endings. A physical line ending
 647    --  is one of:
 648    --
 649    --     CR on its own (MAC System 7)
 650    --     LF on its own (Unix and unix-like systems)
 651    --     CR/LF (DOS, Windows)
 652    --     Wide character in Separator,Line or Separator,Paragraph category
 653    --
 654    --     Note: we no longer recognize LF/CR (which we did in some earlier
 655    --     versions of GNAT. The reason for this is that this sequence is not
 656    --     used and recognizing it generated confusion. For example given the
 657    --     sequence LF/CR/LF we were interpreting that as (LF/CR) ending the
 658    --     first line and a blank line ending with CR following, but it is
 659    --     clearly better to interpret this as LF, with a blank line terminated
 660    --     by CR/LF, given that LF and CR/LF are both in common use, but no
 661    --     system we know of uses LF/CR.
 662    --
 663    --  A logical line ending (that is not a physical line ending) is one of:
 664    --
 665    --     VT on its own
 666    --     FF on its own
 667    --
 668    --  On return, P is bumped past the line ending sequence (one of the above
 669    --  seven possibilities). Physical is set to True to indicate that a
 670    --  physical end of line was encountered, in which case this routine also
 671    --  makes sure that the lines table for the current source file has an
 672    --  appropriate entry for the start of the new physical line.
 673
 674    procedure Sloc_Range (N : Node_Id; Min, Max : out Source_Ptr);
 675    --  Given a node, returns the minimum and maximum source locations of any
 676    --  node in the syntactic subtree for the node. This is not quite the same
 677    --  as the locations of the first and last token in the node construct
 678    --  because parentheses at the outer level do not have a recorded Sloc.
 679    --
 680    --  Note: At each step of the tree traversal, we make sure to go back to
 681    --  the Original_Node, since this function is concerned about original
 682    --  (source) locations.
 683    --
 684    --  Note: if the tree for the expression contains no "real" Sloc values,
 685    --  i.e. values > No_Location, then both Min and Max are set to
 686    --  Sloc (Original_Node (N)).
 687
 688    function Source_Offset (S : Source_Ptr) return Nat;
 689    --  Returns the zero-origin offset of the given source location from the
 690    --  start of its corresponding unit. This is used for creating canonical
 691    --  names in some situations.
 692
 693    procedure Write_Location (P : Source_Ptr);
 694    --  Writes P, in the form fff:nn:cc, where fff, nn, cc are the file name,
 695    --  line number and column corresponding to the given source location. If
 696    --  the location is within an instantiation, then the instance location is
 697    --  appended, enclosed in square brackets, which can nest if necessary. This
 698    --  is used only for debugging output.
 699
 700    procedure wl (P : Source_Ptr);
 701    pragma Export (Ada, wl);
 702    --  Equivalent to Write_Location (P); Write_Eol; for calls from GDB
 703
 704    procedure Write_Time_Stamp (S : Source_File_Index);
 705    --  Writes time stamp of specified file in YY-MM-DD HH:MM.SS format
 706
 707    procedure Clear_Source_File_Table;
 708    --  This procedure frees memory allocated in the Source_File table (in the
 709    --  private). It should only be used when it is guaranteed that all source
 710    --  files that have been loaded so far will not be accessed before being
 711    --  reloaded. It is intended for tools that parse several times sources,
 712    --  to avoid memory leaks.
 713
 714 private
 715    pragma Inline (File_Name);
 716    pragma Inline (Full_File_Name);
 717    pragma Inline (File_Type);
 718    pragma Inline (Reference_Name);
 719    pragma Inline (Full_Ref_Name);
 720    pragma Inline (Debug_Source_Name);
 721    pragma Inline (Full_Debug_Name);
 722    pragma Inline (Instance);
 723    pragma Inline (License);
 724    pragma Inline (Num_SRef_Pragmas);
 725    pragma Inline (First_Mapped_Line);
 726    pragma Inline (Source_Text);
 727    pragma Inline (Source_First);
 728    pragma Inline (Source_Last);
 729    pragma Inline (Time_Stamp);
 730    pragma Inline (Source_Checksum);
 731    pragma Inline (Last_Source_Line);
 732    pragma Inline (Keyword_Casing);
 733    pragma Inline (Identifier_Casing);
 734    pragma Inline (Inlined_Call);
 735    pragma Inline (Inlined_Body);
 736    pragma Inline (Inherited_Pragma);
 737    pragma Inline (Template);
 738    pragma Inline (Unit);
 739
 740    pragma Inline (Set_Keyword_Casing);
 741    pragma Inline (Set_Identifier_Casing);
 742
 743    pragma Inline (Last_Source_File);
 744    pragma Inline (Num_Source_Files);
 745    pragma Inline (Num_Source_Lines);
 746
 747    pragma Inline (Line_Start);
 748
 749    No_Instance_Id : constant Instance_Id := 0;
 750
 751    -------------------------
 752    -- Source_Lines Tables --
 753    -------------------------
 754
 755    type Lines_Table_Type is
 756      array (Physical_Line_Number) of Source_Ptr;
 757    --  Type used for lines table. The entries are indexed by physical line
 758    --  numbers. The values are the starting Source_Ptr values for the start
 759    --  of the corresponding physical line. Note that we make this a bogus
 760    --  big array, sized as required, so that we avoid the use of fat pointers.
 761
 762    type Lines_Table_Ptr is access all Lines_Table_Type;
 763    --  Type used for pointers to line tables
 764
 765    type Logical_Lines_Table_Type is
 766      array (Physical_Line_Number) of Logical_Line_Number;
 767    --  Type used for logical lines table. This table is used if a source
 768    --  reference pragma is present. It is indexed by physical line numbers,
 769    --  and contains the corresponding logical line numbers. An entry that
 770    --  corresponds to a source reference pragma is set to No_Line_Number.
 771    --  Note that we make this a bogus big array, sized as required, so that
 772    --  we avoid the use of fat pointers.
 773
 774    type Logical_Lines_Table_Ptr is access all Logical_Lines_Table_Type;
 775    --  Type used for pointers to logical line tables
 776
 777    -----------------------
 778    -- Source_File Table --
 779    -----------------------
 780
 781    --  See earlier descriptions for meanings of public fields
 782
 783    type Source_File_Record is record
 784       File_Name         : File_Name_Type;
 785       Reference_Name    : File_Name_Type;
 786       Debug_Source_Name : File_Name_Type;
 787       Full_Debug_Name   : File_Name_Type;
 788       Full_File_Name    : File_Name_Type;
 789       Full_Ref_Name     : File_Name_Type;
 790       Instance          : Instance_Id;
 791       Num_SRef_Pragmas  : Nat;
 792       First_Mapped_Line : Logical_Line_Number;
 793       Source_Text       : Source_Buffer_Ptr;
 794       Source_First      : Source_Ptr;
 795       Source_Last       : Source_Ptr;
 796       Source_Checksum   : Word;
 797       Last_Source_Line  : Physical_Line_Number;
 798       Template          : Source_File_Index;
 799       Unit              : Unit_Number_Type;
 800       Time_Stamp        : Time_Stamp_Type;
 801       File_Type         : Type_Of_File;
 802       Inlined_Call      : Source_Ptr;
 803       Inlined_Body      : Boolean;
 804       Inherited_Pragma  : Boolean;
 805       License           : License_Type;
 806       Keyword_Casing    : Casing_Type;
 807       Identifier_Casing : Casing_Type;
 808
 809       --  The following fields are for internal use only (i.e. only in the
 810       --  body of Sinput or its children, with no direct access by clients).
 811
 812       Sloc_Adjust : Source_Ptr;
 813       --  A value to be added to Sloc values for this file to reference the
 814       --  corresponding lines table. This is zero for the non-instantiation
 815       --  case, and set so that the addition references the ultimate template
 816       --  for the instantiation case. See Sinput-L for further details.
 817
 818       Lines_Table : Lines_Table_Ptr;
 819       --  Pointer to lines table for this source. Updated as additional
 820       --  lines are accessed using the Skip_Line_Terminators procedure.
 821       --  Note: the lines table for an instantiation entry refers to the
 822       --  original line numbers of the template see Sinput-L for details.
 823
 824       Logical_Lines_Table : Logical_Lines_Table_Ptr;
 825       --  Pointer to logical lines table for this source. Non-null only if
 826       --  a source reference pragma has been processed. Updated as lines
 827       --  are accessed using the Skip_Line_Terminators procedure.
 828
 829       Lines_Table_Max : Physical_Line_Number;
 830       --  Maximum subscript values for currently allocated Lines_Table
 831       --  and (if present) the allocated Logical_Lines_Table. The value
 832       --  Max_Source_Line gives the maximum used value, this gives the
 833       --  maximum allocated value.
 834
 835       Index : Source_File_Index := 123456789; -- for debugging
 836    end record;
 837
 838    --  The following representation clause ensures that the above record
 839    --  has no holes. We do this so that when instances of this record are
 840    --  written by Tree_Gen, we do not write uninitialized values to the file.
 841
 842    AS : constant Pos := Standard'Address_Size;
 843
 844    for Source_File_Record use record
 845       File_Name           at  0 range 0 .. 31;
 846       Reference_Name      at  4 range 0 .. 31;
 847       Debug_Source_Name   at  8 range 0 .. 31;
 848       Full_Debug_Name     at 12 range 0 .. 31;
 849       Full_File_Name      at 16 range 0 .. 31;
 850       Full_Ref_Name       at 20 range 0 .. 31;
 851       Instance            at 48 range 0 .. 31;
 852       Num_SRef_Pragmas    at 24 range 0 .. 31;
 853       First_Mapped_Line   at 28 range 0 .. 31;
 854       Source_First        at 32 range 0 .. 31;
 855       Source_Last         at 36 range 0 .. 31;
 856       Source_Checksum     at 40 range 0 .. 31;
 857       Last_Source_Line    at 44 range 0 .. 31;
 858       Template            at 52 range 0 .. 31;
 859       Unit                at 56 range 0 .. 31;
 860       Time_Stamp          at 60 range 0 .. 8 * Time_Stamp_Length - 1;
 861       File_Type           at 74 range 0 .. 7;
 862       Inlined_Call        at 88 range 0 .. 31;
 863       Inlined_Body        at 75 range 0 .. 0;
 864       Inherited_Pragma    at 75 range 1 .. 1;
 865       License             at 76 range 0 .. 7;
 866       Keyword_Casing      at 77 range 0 .. 7;
 867       Identifier_Casing   at 78 range 0 .. 15;
 868       Sloc_Adjust         at 80 range 0 .. 31;
 869       Lines_Table_Max     at 84 range 0 .. 31;
 870       Index               at 92 range 0 .. 31;
 871
 872       --  The following fields are pointers, so we have to specialize their
 873       --  lengths using pointer size, obtained above as Standard'Address_Size.
 874       --  Note that Source_Text is a fat pointer, so it has size = AS*2.
 875
 876       Source_Text         at 96 range 0      .. AS * 2 - 1;
 877       Lines_Table         at 96 range AS * 2 .. AS * 3 - 1;
 878       Logical_Lines_Table at 96 range AS * 3 .. AS * 4 - 1;
 879    end record; -- Source_File_Record
 880
 881    for Source_File_Record'Size use 96 * 8 + AS * 4;
 882    --  This ensures that we did not leave out any fields
 883
 884    package Source_File is new Table.Table
 885      (Table_Component_Type => Source_File_Record,
 886       Table_Index_Type     => Source_File_Index,
 887       Table_Low_Bound      => 1,
 888       Table_Initial        => Alloc.Source_File_Initial,
 889       Table_Increment      => Alloc.Source_File_Increment,
 890       Table_Name           => "Source_File");
 891
 892    --  Auxiliary table containing source location of instantiations. Index 0
 893    --  is used for code that does not come from an instance.
 894
 895    package Instances is new Table.Table
 896      (Table_Component_Type => Source_Ptr,
 897       Table_Index_Type     => Instance_Id,
 898       Table_Low_Bound      => 0,
 899       Table_Initial        => Alloc.Source_File_Initial,
 900       Table_Increment      => Alloc.Source_File_Increment,
 901       Table_Name           => "Instances");
 902
 903    -----------------
 904    -- Subprograms --
 905    -----------------
 906
 907    procedure Alloc_Line_Tables
 908      (S       : in out Source_File_Record;
 909       New_Max : Nat);
 910    --  Allocate or reallocate the lines table for the given source file so
 911    --  that it can accommodate at least New_Max lines. Also allocates or
 912    --  reallocates logical lines table if source ref pragmas are present.
 913
 914    procedure Add_Line_Tables_Entry
 915      (S : in out Source_File_Record;
 916       P : Source_Ptr);
 917    --  Increment line table size by one (reallocating the lines table if
 918    --  needed) and set the new entry to contain the value P. Also bumps
 919    --  the Source_Line_Count field. If source reference pragmas are
 920    --  present, also increments logical lines table size by one, and
 921    --  sets new entry.
 922
 923    procedure Trim_Lines_Table (S : Source_File_Index);
 924    --  Set lines table size for entry S in the source file table to
 925    --  correspond to the current value of Num_Source_Lines, releasing
 926    --  any unused storage. This is used by Sinput.L and Sinput.D.
 927
 928    procedure Set_Source_File_Index_Table (Xnew : Source_File_Index);
 929    --  Sets entries in the Source_File_Index_Table for the newly created
 930    --  Source_File table entry whose index is Xnew. The Source_First and
 931    --  Source_Last fields of this entry must be set before the call.
 932    --  See package body for details.
 933
 934    type Dope_Rec is record
 935       First, Last : Source_Ptr'Base;
 936    end record;
 937    Dope_Rec_Size : constant := 2 * Source_Ptr'Base'Size;
 938    for Dope_Rec'Size use Dope_Rec_Size;
 939    for Dope_Rec'Alignment use Dope_Rec_Size / 8;
 940    type Dope_Ptr is access all Dope_Rec;
 941
 942    procedure Set_Dope
 943      (Src : System.Address; New_Dope : Dope_Ptr);
 944    --  Src is the address of a variable of type Source_Buffer_Ptr, which is a
 945    --  fat pointer. This sets the dope part of the fat pointer to point to the
 946    --  specified New_Dope. This low-level processing is used to make the
 947    --  Source_Text of an instance point to the same text as the template, but
 948    --  with different bounds.
 949
 950    procedure Free_Dope (Src : System.Address);
 951    --  Calls Unchecked_Deallocation on the dope part of the fat pointer Src
 952
 953    procedure Free_Source_Buffer (Src : in out Source_Buffer_Ptr);
 954    --  Deallocates the source buffer
 955
 956 end Sinput;