1 ------------------------------------------------------------------------------
3 -- GNAT COMPILER COMPONENTS --
9 -- Copyright (C) 1992-2006, Free Software Foundation, Inc. --
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. --
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. --
29 -- GNAT was originally developed by the GNAT team at New York University. --
30 -- Extensive contributions were provided by Ada Core Technologies Inc. --
32 ------------------------------------------------------------------------------
36 with Hostparm; use Hostparm;
37 with System; use System;
38 with Types; use Types;
42 -- WARNING: There is a C version of this package. Any changes to this
43 -- source file must be properly reflected in the C header file namet.h
44 -- which is created manually from namet.ads and namet.adb.
46 -- This package contains routines for handling the names table. The table
47 -- is used to store character strings for identifiers and operator symbols,
48 -- as well as other string values such as unit names and file names.
50 -- The forms of the entries are as follows:
52 -- Identifiers Stored with upper case letters folded to lower case. Upper
53 -- half (16#80# bit set) and wide characters are stored
54 -- in an encoded form (Uhh for upper half char, Whhhh
55 -- for wide characters, WWhhhhhhhh as provided by the
56 -- routine Store_Encoded_Character, where hh are hex
57 -- digits for the character code using lower case a-f).
58 -- Normally the use of U or W in other internal names is
59 -- avoided, but these letters may be used in internal
60 -- names (without this special meaning), if they appear
61 -- as the last character of the name, or they are
62 -- followed by an upper case letter (other than the WW
63 -- sequence), or an underscore.
65 -- Operator symbols Stored with an initial letter O, and the remainder
66 -- of the name is the lower case characters XXX where
67 -- the name is Name_Op_XXX, see Snames spec for a full
68 -- list of the operator names. Normally the use of O
69 -- in other internal names is avoided, but it may be
70 -- used in internal names (without this special meaning)
71 -- if it is the last character of the name, or if it is
72 -- followed by an upper case letter or an underscore.
74 -- Character literals Character literals have names that are used only for
75 -- debugging and error message purposes. The form is a
76 -- upper case Q followed by a single lower case letter,
77 -- or by a Uxx/Wxxxx/WWxxxxxxx encoding as described for
78 -- identifiers. The Set_Character_Literal_Name procedure
79 -- should be used to construct these encodings. Normally
80 -- the use of O in other internal names is avoided, but
81 -- it may be used in internal names (without this special
82 -- meaning) if it is the last character of the name, or
83 -- if it is followed by an upper case letter or an
86 -- Unit names Stored with upper case letters folded to lower case,
87 -- using Uhh/Whhhh/WWhhhhhhhh encoding as described for
88 -- identifiers, and a %s or %b suffix for specs/bodies.
89 -- See package Uname for further details.
91 -- File names Are stored in the form provided by Osint. Typically
92 -- they may include wide character escape sequences and
93 -- upper case characters (in non-encoded form). Casing
94 -- is also derived from the external environment. Note
95 -- that file names provided by Osint must generally be
96 -- consistent with the names from Fname.Get_File_Name.
98 -- Other strings The names table is also used as a convenient storage
99 -- location for other variable length strings such as
100 -- error messages etc. There are no restrictions on what
101 -- characters may appear for such entries.
103 -- Note: the encodings Uhh (upper half characters), Whhhh (wide characters),
104 -- WWhhhhhhhh (wide wide characters) and Qx (character literal names) are
105 -- described in the spec, since they are visible throughout the system (e.g.
106 -- in debugging output). However, no code should depend on these particular
107 -- encodings, so it should be possible to change the encodings by making
108 -- changes only to the Namet specification (to change these comments) and the
109 -- body (which actually implements the encodings).
111 -- The names are hashed so that a given name appears only once in the table,
112 -- except that names entered with Name_Enter as opposed to Name_Find are
113 -- omitted from the hash table.
115 -- The first 26 entries in the names table (with Name_Id values in the range
116 -- First_Name_Id .. First_Name_Id + 25) represent names which are the one
117 -- character lower case letters in the range a-z, and these names are created
118 -- and initialized by the Initialize procedure.
120 -- Two values, one of type Int and one of type Byte, are stored with each
121 -- names table entry and subprograms are provided for setting and retrieving
122 -- these associated values. The usage of these values is up to the client. In
123 -- the compiler, the Int field is used to point to a chain of potentially
124 -- visible entities (see Sem.Ch8 for details), and the Byte field is used to
125 -- hold the Token_Type value for reserved words (see Sem for details). In the
126 -- binder, the Byte field is unused, and the Int field is used in various
127 -- ways depending on the name involved (see binder documentation).
129 Name_Buffer : String (1 .. 4 * Max_Line_Length);
130 -- This buffer is used to set the name to be stored in the table for the
131 -- Name_Find call, and to retrieve the name for the Get_Name_String call.
132 -- The limit here is intended to be an infinite value that ensures that we
133 -- never overflow the buffer (names this long are too absurd to worry!)
136 -- Length of name stored in Name_Buffer. Used as an input parameter for
137 -- Name_Find, and as an output value by Get_Name_String, or Write_Name.
144 -- Called at the end of a use of the Namet package (before a subsequent
145 -- call to Initialize). Currently this routine is only used to generate
148 procedure Get_Name_String (Id : Name_Id);
149 -- Get_Name_String is used to retrieve the string associated with an entry
150 -- in the names table. The resulting string is stored in Name_Buffer and
151 -- Name_Len is set. It is an error to call Get_Name_String with one of the
152 -- special name Id values (No_Name or Error_Name).
154 function Get_Name_String (Id : Name_Id) return String;
155 -- This functional form returns the result as a string without affecting
156 -- the contents of either Name_Buffer or Name_Len.
158 procedure Get_Unqualified_Name_String (Id : Name_Id);
159 -- Similar to the above except that qualification (as defined in unit
160 -- Exp_Dbug) is removed (including both preceding __ delimited names, and
161 -- also the suffixes used to indicate package body entities and to
162 -- distinguish between overloaded entities). Note that names are not
163 -- qualified until just before the call to gigi, so this routine is only
164 -- needed by processing that occurs after gigi has been called. This
165 -- includes all ASIS processing, since ASIS works on the tree written
166 -- after gigi has been called.
168 procedure Get_Name_String_And_Append (Id : Name_Id);
169 -- Like Get_Name_String but the resulting characters are appended to the
170 -- current contents of the entry stored in Name_Buffer, and Name_Len is
171 -- incremented to include the added characters.
173 procedure Get_Decoded_Name_String (Id : Name_Id);
174 -- Same calling sequence an interface as Get_Name_String, except that the
175 -- result is decoded, so that upper half characters and wide characters
176 -- appear as originally found in the source program text, operators have
177 -- their source forms (special characters and enclosed in quotes), and
178 -- character literals appear surrounded by apostrophes.
180 procedure Get_Unqualified_Decoded_Name_String (Id : Name_Id);
181 -- Similar to the above except that qualification (as defined in unit
182 -- Exp_Dbug) is removed (including both preceding __ delimited names, and
183 -- also the suffix used to indicate package body entities). Note that
184 -- names are not qualified until just before the call to gigi, so this
185 -- routine is only needed by processing that occurs after gigi has been
186 -- called. This includes all ASIS processing, since ASIS works on the tree
187 -- written after gigi has been called.
189 procedure Get_Decoded_Name_String_With_Brackets (Id : Name_Id);
190 -- This routine is similar to Decoded_Name, except that the brackets
191 -- notation (Uhh replaced by ["hh"], Whhhh replaced by ["hhhh"],
192 -- WWhhhhhhhh replaced by ["hhhhhhhh"]) is used for all non-lower half
193 -- characters, regardless of how Opt.Wide_Character_Encoding_Method is
194 -- set, and also in that characters in the range 16#80# .. 16#FF# are
195 -- converted to brackets notation in all cases. This routine can be used
196 -- when there is a requirement for a canonical representation not affected
197 -- by the character set options (e.g. in the binder generation of
200 function Get_Name_Table_Byte (Id : Name_Id) return Byte;
201 pragma Inline (Get_Name_Table_Byte);
202 -- Fetches the Byte value associated with the given name
204 function Get_Name_Table_Info (Id : Name_Id) return Int;
205 pragma Inline (Get_Name_Table_Info);
206 -- Fetches the Int value associated with the given name
208 function Is_Operator_Name (Id : Name_Id) return Boolean;
209 -- Returns True if name given is of the form of an operator (that
210 -- is, it starts with an upper case O).
212 procedure Initialize;
213 -- Initializes the names table, including initializing the first 26
214 -- entries in the table (for the 1-character lower case names a-z) Note
215 -- that Initialize must not be called if Tree_Read is used.
218 -- Lock name table before calling back end. Space for up to 10 extra
219 -- names and 1000 extra characters is reserved before the table is locked.
222 -- Unlocks the name table to allow use of the 10 extra names and 1000
223 -- extra characters reserved by the Lock call. See gnat1drv for details of
224 -- the need for this.
226 function Length_Of_Name (Id : Name_Id) return Nat;
227 pragma Inline (Length_Of_Name);
228 -- Returns length of given name in characters. This is the length of the
229 -- encoded name, as stored in the names table, the result is equivalent to
230 -- calling Get_Name_String and reading Name_Len, except that a call to
231 -- Length_Of_Name does not affect the contents of Name_Len and Name_Buffer.
233 function Name_Chars_Address return System.Address;
234 -- Return starting address of name characters table (used in Back_End call
237 function Name_Find return Name_Id;
238 -- Name_Find is called with a string stored in Name_Buffer whose length is
239 -- in Name_Len (i.e. the characters of the name are in subscript positions
240 -- 1 to Name_Len in Name_Buffer). It searches the names table to see if
241 -- the string has already been stored. If so the Id of the existing entry
242 -- is returned. Otherwise a new entry is created with its Name_Table_Info
243 -- field set to zero. The contents of Name_Buffer and Name_Len are not
244 -- modified by this call. Note that it is permissible for Name_Len to be
245 -- set to zero to lookup the null name string.
247 function Name_Enter return Name_Id;
248 -- Name_Enter has the same calling interface as Name_Find. The difference
249 -- is that it does not search the table for an existing match, and also
250 -- subsequent Name_Find calls using the same name will not locate the
251 -- entry created by this call. Thus multiple calls to Name_Enter with the
252 -- same name will create multiple entries in the name table with different
253 -- Name_Id values. This is useful in the case of created names, which are
254 -- never expected to be looked up. Note: Name_Enter should never be used
255 -- for one character names, since these are efficiently located without
256 -- hashing by Name_Find in any case.
258 function Name_Entries_Address return System.Address;
259 -- Return starting address of Names table (used in Back_End call to Gigi)
261 function Name_Entries_Count return Nat;
262 -- Return current number of entries in the names table
264 function Is_OK_Internal_Letter (C : Character) return Boolean;
265 pragma Inline (Is_OK_Internal_Letter);
266 -- Returns true if C is a suitable character for using as a prefix or a
267 -- suffix of an internally generated name, i.e. it is an upper case letter
268 -- other than one of the ones used for encoding source names (currently
269 -- the set of reserved letters is O, Q, U, W) and also returns False for
270 -- the letter X, which is reserved for debug output (see Exp_Dbug).
272 function Is_Internal_Name (Id : Name_Id) return Boolean;
273 -- Returns True if the name is an internal name (i.e. contains a character
274 -- for which Is_OK_Internal_Letter is true, or if the name starts or ends
275 -- with an underscore. This call destroys the value of Name_Len and
276 -- Name_Buffer (it loads these as for Get_Name_String).
278 -- Note: if the name is qualified (has a double underscore), then only the
279 -- final entity name is considered, not the qualifying names. Consider for
280 -- example that the name:
284 -- is not an internal name, because the B comes from the internal name of
285 -- a qualifying block, but the xyz means that this was indeed a declared
286 -- identifier called "xyz" within this block and there is nothing internal
289 function Is_Internal_Name return Boolean;
290 -- Like the form with an Id argument, except that the name to be tested is
291 -- passed in Name_Buffer and Name_Len (which are not affected by the call).
292 -- Name_Buffer (it loads these as for Get_Name_String).
294 function Is_Valid_Name (Id : Name_Id) return Boolean;
295 -- True if Id is a valid name -- points to a valid entry in the
296 -- Name_Entries table.
298 procedure Reset_Name_Table;
299 -- This procedure is used when there are multiple source files to reset
300 -- the name table info entries associated with current entries in the
301 -- names table. There is no harm in keeping the names entries themselves
302 -- from one compilation to another, but we can't keep the entity info,
303 -- since this refers to tree nodes, which are destroyed between each main
306 procedure Add_Char_To_Name_Buffer (C : Character);
307 pragma Inline (Add_Char_To_Name_Buffer);
308 -- Add given character to the end of the string currently stored in the
309 -- Name_Buffer, incrementing Name_Len.
311 procedure Add_Nat_To_Name_Buffer (V : Nat);
312 -- Add decimal representation of given value to the end of the string
313 -- currently stored in Name_Buffer, incrementing Name_Len as required.
315 procedure Add_Str_To_Name_Buffer (S : String);
316 -- Add characters of string S to the end of the string currently stored
317 -- in the Name_Buffer, incrementing Name_Len by the length of the string.
319 procedure Set_Character_Literal_Name (C : Char_Code);
320 -- This procedure sets the proper encoded name for the character literal
321 -- for the given character code. On return Name_Buffer and Name_Len are
322 -- set to reflect the stored name.
324 procedure Set_Name_Table_Info (Id : Name_Id; Val : Int);
325 pragma Inline (Set_Name_Table_Info);
326 -- Sets the Int value associated with the given name
328 procedure Set_Name_Table_Byte (Id : Name_Id; Val : Byte);
329 pragma Inline (Set_Name_Table_Byte);
330 -- Sets the Byte value associated with the given name
332 procedure Store_Encoded_Character (C : Char_Code);
333 -- Stores given character code at the end of Name_Buffer, updating the
334 -- value in Name_Len appropriately. Lower case letters and digits are
335 -- stored unchanged. Other 8-bit characters are stored using the Uhh
336 -- encoding (hh = hex code), other 16-bit wide character values are stored
337 -- using the Whhhh (hhhh = hex code) encoding, and other 32-bit wide wide
338 -- character values are stored using the WWhhhhhhhh (hhhhhhhh = hex code).
339 -- Note that this procedure does not fold upper case letters (they are
340 -- stored using the Uhh encoding). If folding is required, it must be done
341 -- by the caller prior to the call.
344 -- Initializes internal tables from current tree file using the relevant
345 -- Table.Tree_Read routines. Note that Initialize should not be called if
346 -- Tree_Read is used. Tree_Read includes all necessary initialization.
348 procedure Tree_Write;
349 -- Writes out internal tables to current tree file using the relevant
350 -- Table.Tree_Write routines.
352 procedure Get_Last_Two_Chars (N : Name_Id; C1, C2 : out Character);
353 -- Obtains last two characters of a name. C1 is last but one character
354 -- and C2 is last character. If name is less than two characters long,
355 -- then both C1 and C2 are set to ASCII.NUL on return.
357 procedure Write_Name (Id : Name_Id);
358 -- Write_Name writes the characters of the specified name using the
359 -- standard output procedures in package Output. No end of line is
360 -- written, just the characters of the name. On return Name_Buffer and
361 -- Name_Len are set as for a call to Get_Name_String. The name is written
362 -- in encoded form (i.e. including Uhh, Whhh, Qx, _op as they appear in
363 -- the name table). If Id is Error_Name, or No_Name, no text is output.
365 procedure Write_Name_Decoded (Id : Name_Id);
366 -- Like Write_Name, except that the name written is the decoded name, as
367 -- described for Get_Decoded_Name_String, and the resulting value stored
368 -- in Name_Len and Name_Buffer is the decoded name.
370 procedure wn (Id : Name_Id);
371 pragma Export (Ada, wn);
372 -- This routine is intended for debugging use only (i.e. it is intended to
373 -- be called from the debugger). It writes the characters of the specified
374 -- name using the standard output procedures in package Output, followed by
375 -- a new line. The name is written in encoded form (i.e. including Uhh,
376 -- Whhh, Qx, _op as they appear in the name table). If Id is Error_Name,
377 -- No_Name, or invalid an appropriate string is written (<Error_Name>,
378 -- <No_Name>, <invalid name>). Unlike Write_Name, this call does not affect
379 -- the contents of Name_Buffer or Name_Len.
381 ---------------------------
382 -- Table Data Structures --
383 ---------------------------
385 -- The following declarations define the data structures used to store
386 -- names. The definitions are in the private part of the package spec,
387 -- rather than the body, since they are referenced directly by gigi.
391 -- This table stores the actual string names. Although logically there is
392 -- no need for a terminating character (since the length is stored in the
393 -- name entry table), we still store a NUL character at the end of every
394 -- name (for convenience in interfacing to the C world).
396 package Name_Chars is new Table.Table (
397 Table_Component_Type => Character,
398 Table_Index_Type => Int,
399 Table_Low_Bound => 0,
400 Table_Initial => Alloc.Name_Chars_Initial,
401 Table_Increment => Alloc.Name_Chars_Increment,
402 Table_Name => "Name_Chars");
404 type Name_Entry is record
405 Name_Chars_Index : Int;
406 -- Starting location of characters in the Name_Chars table minus one
407 -- (i.e. pointer to character just before first character). The reason
408 -- for the bias of one is that indexes in Name_Buffer are one's origin,
409 -- so this avoids unnecessary adds and subtracts of 1.
412 -- Length of this name in characters
415 -- Byte value associated with this name
417 Name_Has_No_Encodings : Boolean;
418 -- This flag is set True if the name entry is known not to contain any
419 -- special character encodings. This is used to speed up repeated calls
420 -- to Get_Decoded_Name_String. A value of False means that it is not
421 -- known whether the name contains any such encodings.
424 -- Link to next entry in names table for same hash code
427 -- Int Value associated with this name
430 -- This is the table that is referenced by Name_Id entries.
431 -- It contains one entry for each unique name in the table.
433 package Name_Entries is new Table.Table (
434 Table_Component_Type => Name_Entry,
435 Table_Index_Type => Name_Id,
436 Table_Low_Bound => First_Name_Id,
437 Table_Initial => Alloc.Names_Initial,
438 Table_Increment => Alloc.Names_Increment,
439 Table_Name => "Name_Entries");