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-2019, Free Software Foundation, Inc.         --
10--                                                                          --
11-- GNAT is free software;  you can  redistribute it  and/or modify it under --
12-- terms of the  GNU General Public License as published  by the Free Soft- --
13-- ware  Foundation;  either version 3,  or (at your option) any later ver- --
14-- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
15-- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
16-- or FITNESS FOR A PARTICULAR PURPOSE.                                     --
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
32with Namet;  use Namet;
33with System; use System;
34with Types;  use Types;
35
36package 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--  WARNING: There is a C version of this package. Any changes to this
46--  source file must be properly reflected in the C header file stringt.h
47
48--  A string constant in this table consists of a series of Char_Code values,
49--  so that 16-bit character codes can be properly handled if this feature
50--  is implemented in the scanner.
51
52--  There is no guarantee that hashing is used in the implementation, although
53--  it may be. This means that the caller cannot count on having the same Id
54--  value for two identical strings stored separately and also cannot count on
55--  the two such Id values being different.
56
57   Null_String_Id : String_Id;
58   --  Gets set to a null string with length zero
59
60   --------------------------------------
61   -- String Table Access Subprograms --
62   --------------------------------------
63
64   procedure Initialize;
65   --  Initializes the strings table for a new compilation. Note that
66   --  Initialize must not be called if Tree_Read is used.
67
68   procedure Lock;
69   --  Lock internal tables before calling back end
70
71   procedure Unlock;
72   --  Unlock internal tables, in case back end needs to modify them
73
74   procedure Mark;
75   --  Take a snapshot of the internal tables. Used in conjunction with Release
76   --  when computing temporary string values that need not be preserved.
77
78   procedure Release;
79   --  Restore the internal tables to the situation when Mark was last called.
80   --  If Release is called with no prior call to Mark, the entire string table
81   --  is cleared to its initial (empty) setting.
82
83   procedure Start_String;
84   --  Sets up for storing a new string in the table. To store a string, a
85   --  call is first made to Start_String, then successive calls are
86   --  made to Store_String_Character to store the characters of the string.
87   --  Finally, a call to End_String terminates the entry and returns it Id.
88
89   procedure Start_String (S : String_Id);
90   --  Like Start_String with no parameter, except that the contents of the
91   --  new string is initialized to be a copy of the given string. A test is
92   --  made to see if S is the last created string, and if so it is shared,
93   --  rather than copied, this can be particularly helpful for the case of
94   --  a continued concatenation of string constants.
95
96   procedure Store_String_Char (C : Char_Code);
97   procedure Store_String_Char (C : Character);
98   --  Store next character of string, see description above for Start_String
99
100   procedure Store_String_Chars (S : String);
101   procedure Store_String_Chars (S : String_Id);
102   --  Store character codes of given string in sequence
103
104   procedure Store_String_Int (N : Int);
105   --  Stored decimal representation of integer with possible leading minus
106
107   procedure Unstore_String_Char;
108   --  Undoes effect of previous Store_String_Char call, used in some error
109   --  situations of unterminated string constants.
110
111   function End_String return String_Id;
112   --  Terminates current string and returns its Id
113
114   function String_Length (Id : String_Id) return Nat;
115   --  Returns length of previously stored string
116
117   function Get_String_Char (Id : String_Id; Index : Int) return Char_Code;
118   pragma Inline (Get_String_Char);
119   --  Obtains the specified character from a stored string. The lower bound
120   --  of stored strings is always 1, so the range is 1 .. String_Length (Id).
121
122   function String_Equal (L, R : String_Id) return Boolean;
123   --  Determines if two string literals represent the same string
124
125   function String_To_Name (S : String_Id) return Name_Id;
126   --  Convert String_Id to Name_Id
127
128   procedure Append (Buf : in out Bounded_String; S : String_Id);
129   --  Append characters of given string to Buf. Error if any characters are
130   --  out of Character range. Does not attempt to do any encoding of
131   --  characters.
132
133   function To_String (S : String_Id) return String;
134   --  Return S as a String
135
136   procedure String_To_Name_Buffer (S : String_Id);
137   --  Place characters of given string in Name_Buffer, setting Name_Len.
138   --  Error if any characters are out of Character range. Does not attempt
139   --  to do any encoding of any characters.
140
141   function String_Chars_Address return System.Address;
142   --  Return address of String_Chars table (used by Back_End call to Gigi)
143
144   function String_From_Name_Buffer
145     (Buf : Bounded_String := Global_Name_Buffer) return String_Id;
146   --  Given a name stored in Buf, returns a string of the corresponding value.
147
148   function Strings_Address return System.Address;
149   --  Return address of Strings table (used by Back_End call to Gigi)
150
151   procedure Tree_Read;
152   --  Initializes internal tables from current tree file using the relevant
153   --  Table.Tree_Read routines. Note that Initialize should not be called if
154   --  Tree_Read is used. Tree_Read includes all necessary initialization.
155
156   procedure Tree_Write;
157   --  Writes out internal tables to current tree file using the relevant
158   --  Table.Tree_Write routines.
159
160   procedure Write_Char_Code (Code : Char_Code);
161   --  Procedure to write a character code value, used for debugging purposes
162   --  for writing character codes. If the character code is in the range
163   --  16#20# .. 16#7E#, then the single graphic character corresponding to
164   --  the code is output. For any other codes in the range 16#00# .. 16#FF#,
165   --  the code is output as ["hh"] where hh is the two digit hex value for
166   --  the code. Codes greater than 16#FF# are output as ["hhhh"] where hhhh
167   --  is the four digit hex representation of the code value (high order
168   --  byte first). Hex letters are always in lower case.
169
170   procedure Write_String_Table_Entry (Id : String_Id);
171   --  Writes a string value with enclosing quotes to the current file using
172   --  routines in package Output. Does not write an end of line character.
173   --  This procedure is used for debug output purposes, and also for output
174   --  of strings specified by pragma Linker Option to the ali file. 7-bit
175   --  ASCII graphics (except for double quote) are output literally.
176   --  The double quote appears as two successive double quotes.
177   --  All other codes, are output as described for Write_Char_Code. For
178   --  example, the string created by folding "A" & ASCII.HT & "Hello" will
179   --  print as "A["09"]Hello". A No_String value prints simply as "no string"
180   --  without surrounding quote marks.
181
182private
183   pragma Inline (End_String);
184   pragma Inline (String_Length);
185
186end Stringt;
187