gcc/ada/stringt.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                              S T R I N G T                               --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --          Copyright (C) 1992-2018, 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.                                     --
  17 --                                                                          --
  18 -- As a special exception under Section 7 of GPL version 3, you are granted --
  19 -- additional permissions described in the GCC Runtime Library Exception,   --
  20 -- version 3.1, as published by the Free Software Foundation.               --
  21 --                                                                          --
  22 -- You should have received a copy of the GNU General Public License and    --
  23 -- a copy of the GCC Runtime Library Exception along with this program;     --
  24 -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
  25 -- <http://www.gnu.org/licenses/>.                                          --
  26 --                                                                          --
  27 -- GNAT was originally developed  by the GNAT team at  New York University. --
  28 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  29 --                                                                          --
  30 ------------------------------------------------------------------------------
  31
  32 with Namet;  use Namet;
  33 with System; use System;
  34 with Types;  use Types;
  35
  36 package Stringt is
  37    pragma Elaborate_Body;
  38    --  This is to make sure Null_String_Id is properly initialized
  39
  40 --  This package contains routines for handling the strings table which is
  41 --  used to store string constants encountered in the source, and also those
  42 --  additional string constants generated by compile time concatenation and
  43 --  other similar processing.
  44
  45 --  A string constant in this table consists of a series of Char_Code values,
  46 --  so that 16-bit character codes can be properly handled if this feature
  47 --  is implemented in the scanner.
  48
  49 --  There is no guarantee that hashing is used in the implementation, although
  50 --  it may be. This means that the caller cannot count on having the same Id
  51 --  value for two identical strings stored separately and also cannot count on
  52 --  the two such Id values being different.
  53
  54    Null_String_Id : String_Id;
  55    --  Gets set to a null string with length zero
  56
  57    --------------------------------------
  58    -- String Table Access Subprograms --
  59    --------------------------------------
  60
  61    procedure Initialize;
  62    --  Initializes the strings table for a new compilation. Note that
  63    --  Initialize must not be called if Tree_Read is used.
  64
  65    procedure Lock;
  66    --  Lock internal tables before calling back end
  67
  68    procedure Unlock;
  69    --  Unlock internal tables, in case back end needs to modify them
  70
  71    procedure Mark;
  72    --  Take a snapshot of the internal tables. Used in conjunction with Release
  73    --  when computing temporary string values that need not be preserved.
  74
  75    procedure Release;
  76    --  Restore the internal tables to the situation when Mark was last called.
  77    --  If Release is called with no prior call to Mark, the entire string table
  78    --  is cleared to its initial (empty) setting.
  79
  80    procedure Start_String;
  81    --  Sets up for storing a new string in the table. To store a string, a
  82    --  call is first made to Start_String, then successive calls are
  83    --  made to Store_String_Character to store the characters of the string.
  84    --  Finally, a call to End_String terminates the entry and returns it Id.
  85
  86    procedure Start_String (S : String_Id);
  87    --  Like Start_String with no parameter, except that the contents of the
  88    --  new string is initialized to be a copy of the given string. A test is
  89    --  made to see if S is the last created string, and if so it is shared,
  90    --  rather than copied, this can be particularly helpful for the case of
  91    --  a continued concatenation of string constants.
  92
  93    procedure Store_String_Char (C : Char_Code);
  94    procedure Store_String_Char (C : Character);
  95    --  Store next character of string, see description above for Start_String
  96
  97    procedure Store_String_Chars (S : String);
  98    procedure Store_String_Chars (S : String_Id);
  99    --  Store character codes of given string in sequence
 100
 101    procedure Store_String_Int (N : Int);
 102    --  Stored decimal representation of integer with possible leading minus
 103
 104    procedure Unstore_String_Char;
 105    --  Undoes effect of previous Store_String_Char call, used in some error
 106    --  situations of unterminated string constants.
 107
 108    function End_String return String_Id;
 109    --  Terminates current string and returns its Id
 110
 111    function String_Length (Id : String_Id) return Nat;
 112    --  Returns length of previously stored string
 113
 114    function Get_String_Char (Id : String_Id; Index : Int) return Char_Code;
 115    pragma Inline (Get_String_Char);
 116    --  Obtains the specified character from a stored string. The lower bound
 117    --  of stored strings is always 1, so the range is 1 .. String_Length (Id).
 118
 119    function String_Equal (L, R : String_Id) return Boolean;
 120    --  Determines if two string literals represent the same string
 121
 122    function String_To_Name (S : String_Id) return Name_Id;
 123    --  Convert String_Id to Name_Id
 124
 125    procedure Append (Buf : in out Bounded_String; S : String_Id);
 126    --  Append characters of given string to Buf. Error if any characters are
 127    --  out of Character range. Does not attempt to do any encoding of
 128    --  characters.
 129
 130    procedure String_To_Name_Buffer (S : String_Id);
 131    --  Place characters of given string in Name_Buffer, setting Name_Len.
 132    --  Error if any characters are out of Character range. Does not attempt
 133    --  to do any encoding of any characters.
 134
 135    function String_Chars_Address return System.Address;
 136    --  Return address of String_Chars table (used by Back_End call to Gigi)
 137
 138    function String_From_Name_Buffer
 139      (Buf : Bounded_String := Global_Name_Buffer) return String_Id;
 140    --  Given a name stored in Buf, returns a string of the corresponding value.
 141
 142    function Strings_Address return System.Address;
 143    --  Return address of Strings table (used by Back_End call to Gigi)
 144
 145    procedure Tree_Read;
 146    --  Initializes internal tables from current tree file using the relevant
 147    --  Table.Tree_Read routines. Note that Initialize should not be called if
 148    --  Tree_Read is used. Tree_Read includes all necessary initialization.
 149
 150    procedure Tree_Write;
 151    --  Writes out internal tables to current tree file using the relevant
 152    --  Table.Tree_Write routines.
 153
 154    procedure Write_Char_Code (Code : Char_Code);
 155    --  Procedure to write a character code value, used for debugging purposes
 156    --  for writing character codes. If the character code is in the range
 157    --  16#20# .. 16#7E#, then the single graphic character corresponding to
 158    --  the code is output. For any other codes in the range 16#00# .. 16#FF#,
 159    --  the code is output as ["hh"] where hh is the two digit hex value for
 160    --  the code. Codes greater than 16#FF# are output as ["hhhh"] where hhhh
 161    --  is the four digit hex representation of the code value (high order
 162    --  byte first). Hex letters are always in lower case.
 163
 164    procedure Write_String_Table_Entry (Id : String_Id);
 165    --  Writes a string value with enclosing quotes to the current file using
 166    --  routines in package Output. Does not write an end of line character.
 167    --  This procedure is used for debug output purposes, and also for output
 168    --  of strings specified by pragma Linker Option to the ali file. 7-bit
 169    --  ASCII graphics (except for double quote) are output literally.
 170    --  The double quote appears as two successive double quotes.
 171    --  All other codes, are output as described for Write_Char_Code. For
 172    --  example, the string created by folding "A" & ASCII.HT & "Hello" will
 173    --  print as "A["09"]Hello". A No_String value prints simply as "no string"
 174    --  without surrounding quote marks.
 175
 176 private
 177    pragma Inline (End_String);
 178    pragma Inline (String_Length);
 179
 180 end Stringt;