1 ------------------------------------------------------------------------------
3 -- GNAT COMPILER COMPONENTS --
9 -- Copyright (C) 1992-2003 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, 59 Temple Place - Suite 330, Boston, --
20 -- MA 02111-1307, 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 System
; use System
;
37 with Types
; use Types
;
41 -- WARNING: There is a C version of this package. Any changes to this
42 -- source file must be properly reflected in the C header file namet.h
43 -- which is created manually from namet.ads and namet.adb.
45 -- This package contains routines for handling the names table. The table
46 -- is used to store character strings for identifiers and operator symbols,
47 -- as well as other string values such as unit names and file names.
49 -- The forms of the entries are as follows:
51 -- Identifiers Stored with upper case letters folded to lower case.
52 -- Upper half (16#80# bit set) and wide characters are
53 -- stored in an encoded form (Uhh for upper half and
54 -- Whhhh for wide characters, as provided by the routine
55 -- Store_Encoded_Character, where hh are hex digits for
56 -- the character code using lower case a-f). Normally
57 -- the use of U or W in other internal names is avoided,
58 -- but these letters may be used in internal names
59 -- (without this special meaning), if the appear as
60 -- the last character of the name, or they are followed
61 -- by an upper case letter or an underscore.
64 -- Operator symbols Stored with an initial letter O, and the remainder
65 -- of the name is the lower case characters XXX where
66 -- the name is Name_Op_XXX, see Snames spec for a full
67 -- list of the operator names. Normally the use of O
68 -- in other internal names is avoided, but it may be
69 -- used in internal names (without this special meaning)
70 -- if it is the last character of the name, or if it is
71 -- followed by an upper case letter or an underscore.
73 -- Character literals Character literals have names that are used only for
74 -- debugging and error message purposes. The form is a
75 -- upper case Q followed by a single lower case letter,
76 -- or by a Uxx or Wxxxx encoding as described for
77 -- identifiers. The Set_Character_Literal_Name procedure
78 -- should be used to construct these encodings. Normally
79 -- the use of O in other internal names is avoided, but
80 -- it may be used in internal names (without this special
81 -- meaning) if it is the last character of the name, or
82 -- if it is followed by an upper case letter or an
85 -- Unit names Stored with upper case letters folded to lower case,
86 -- using Uhh/Whhhh encoding as described for identifiers,
87 -- and a %s or %b suffix for specs/bodies. See package
88 -- Uname for further details.
90 -- File names Are stored in the form provided by Osint. Typically
91 -- they may include wide character escape sequences and
92 -- upper case characters (in non-encoded form). Casing
93 -- is also derived from the external environment. Note
94 -- that file names provided by Osint must generally be
95 -- consistent with the names from Fname.Get_File_Name.
97 -- Other strings The names table is also used as a convenient storage
98 -- location for other variable length strings such as
99 -- error messages etc. There are no restrictions on what
100 -- characters may appear for such entries.
102 -- Note: the encodings Uhh (upper half characters), Whhhh (wide characters),
103 -- and Qx (character literal names) are described in the spec, since they
104 -- are visible throughout the system (e.g. in debugging output). However,
105 -- no code should depend on these particular encodings, so it should be
106 -- possible to change the encodings by making changes only to the Namet
107 -- specification (to change these comments) and the body (which actually
108 -- implements the encodings).
110 -- The names are hashed so that a given name appears only once in the table,
111 -- except that names entered with Name_Enter as opposed to Name_Find are
112 -- omitted from the hash table.
114 -- The first 26 entries in the names table (with Name_Id values in the range
115 -- First_Name_Id .. First_Name_Id + 25) represent names which are the one
116 -- character lower case letters in the range a-z, and these names are created
117 -- and initialized by the Initialize procedure.
119 -- Two values, one of type Int and one of type Byte, are stored with each
120 -- names table entry and subprograms are provided for setting and retrieving
121 -- these associated values. The usage of these values is up to the client.
122 -- In the compiler, the Int field is used to point to a chain of potentially
123 -- visible entities (see Sem.Ch8 for details), and the Byte field is used
124 -- to hold the Token_Type value for reserved words (see Sem for details).
125 -- In the binder, the Byte field is unused, and the Int field is used in
126 -- various ways depending on the name involved (see binder documentation).
128 Name_Buffer
: String (1 .. 16*1024);
129 -- This buffer is used to set the name to be stored in the table for the
130 -- Name_Find call, and to retrieve the name for the Get_Name_String call.
131 -- The plus 1 in the length allows for cases of adding ASCII.NUL. The
132 -- 16K 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
151 -- and Name_Len is set. It is an error to call Get_Name_String with one
152 -- of the 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,
161 -- and 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
164 -- only needed by processing that occurs after gigi has been called.
165 -- This includes all ASIS processing, since ASIS works on the tree
166 -- written 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
170 -- the current contents of the entry stored in Name_Buffer, and Name_Len
171 -- is 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,
183 -- and also the suffix used to indicate package body entities). Note
184 -- that names are not qualified until just before the call to gigi, so
185 -- this routine is only needed by processing that occurs after gigi has
186 -- been called. This includes all ASIS processing, since ASIS works on
187 -- the tree 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"]) is
192 -- used for all non-lower half characters, regardless of the setting
193 -- of Opt.Wide_Character_Encoding_Method, and also in that characters
194 -- in the range 16#80# .. 16#FF# are converted to brackets notation
195 -- in all cases. This routine can be used when there is a requirement
196 -- for a canonical representation not affected by the character set
197 -- options (e.g. in the binder generation of symbols).
199 function Get_Name_Table_Byte
(Id
: Name_Id
) return Byte
;
200 pragma Inline
(Get_Name_Table_Byte
);
201 -- Fetches the Byte value associated with the given name
203 function Get_Name_Table_Info
(Id
: Name_Id
) return Int
;
204 pragma Inline
(Get_Name_Table_Info
);
205 -- Fetches the Int value associated with the given name
207 procedure Initialize
;
208 -- Initializes the names table, including initializing the first 26
209 -- entries in the table (for the 1-character lower case names a-z)
210 -- Note that Initialize must not be called if Tree_Read is used.
213 -- Lock name table before calling back end. Space for up to 10 extra
214 -- names and 1000 extra characters is reserved before the table is locked.
217 -- Unlocks the name table to allow use of the 10 extra names and 1000
218 -- extra characters reserved by the Lock call. See gnat1drv for details
219 -- of the need for this.
221 function Length_Of_Name
(Id
: Name_Id
) return Nat
;
222 pragma Inline
(Length_Of_Name
);
223 -- Returns length of given name in characters. This is the length of the
224 -- encoded name, as stored in the names table, the result is equivalent to
225 -- calling Get_Name_String and reading Name_Len, except that a call to
226 -- Length_Of_Name does not affect the contents of Name_Len and Name_Buffer.
228 function Name_Chars_Address
return System
.Address
;
229 -- Return starting address of name characters table (used in Back_End
232 function Name_Find
return Name_Id
;
233 -- Name_Find is called with a string stored in Name_Buffer whose length
234 -- is in Name_Len (i.e. the characters of the name are in subscript
235 -- positions 1 to Name_Len in Name_Buffer). It searches the names
236 -- table to see if the string has already been stored. If so the Id of
237 -- the existing entry is returned. Otherwise a new entry is created with
238 -- its Name_Table_Info field set to zero. The contents of Name_Buffer
239 -- and Name_Len are not modified by this call. Note that it is permissible
240 -- for Name_Len to be set to zero to lookup the null name string.
242 function Name_Enter
return Name_Id
;
243 -- Name_Enter has the same calling interface as Name_Find. The difference
244 -- is that it does not search the table for an existing match, and also
245 -- subsequent Name_Find calls using the same name will not locate the
246 -- entry created by this call. Thus multiple calls to Name_Enter with the
247 -- same name will create multiple entries in the name table with different
248 -- Name_Id values. This is useful in the case of created names, which are
249 -- never expected to be looked up. Note: Name_Enter should never be used
250 -- for one character names, since these are efficiently located without
251 -- hashing by Name_Find in any case.
253 function Name_Entries_Address
return System
.Address
;
254 -- Return starting address of Names table. Used in Back_End call to Gigi.
256 function Name_Entries_Count
return Nat
;
257 -- Return current number of entries in the names table
259 function Is_OK_Internal_Letter
(C
: Character) return Boolean;
260 pragma Inline
(Is_OK_Internal_Letter
);
261 -- Returns true if C is a suitable character for using as a prefix or a
262 -- suffix of an internally generated name, i.e. it is an upper case letter
263 -- other than one of the ones used for encoding source names (currently
264 -- the set of reserved letters is O, Q, U, W) and also returns False for
265 -- the letter X, which is reserved for debug output (see Exp_Dbug).
267 function Is_Internal_Name
(Id
: Name_Id
) return Boolean;
268 -- Returns True if the name is an internal name (i.e. contains a character
269 -- for which Is_OK_Internal_Letter is true, or if the name starts or ends
270 -- with an underscore. This call destroys the value of Name_Len and
271 -- Name_Buffer (it loads these as for Get_Name_String).
273 -- Note: if the name is qualified (has a double underscore), then
274 -- only the final entity name is considered, not the qualifying
275 -- names. Consider for example that the name:
279 -- is not an internal name, because the B comes from the internal
280 -- name of a qualifying block, but the xyz means that this was
281 -- indeed a declared identifier called "xyz" within this block
282 -- and there is nothing internal about that name.
284 function Is_Internal_Name
return Boolean;
285 -- Like the form with an Id argument, except that the name to be tested is
286 -- passed in Name_Buffer and Name_Len (which are not affected by the call).
287 -- Name_Buffer (it loads these as for Get_Name_String).
289 procedure Reset_Name_Table
;
290 -- This procedure is used when there are multiple source files to reset
291 -- the name table info entries associated with current entries in the
292 -- names table. There is no harm in keeping the names entries themselves
293 -- from one compilation to another, but we can't keep the entity info,
294 -- since this refers to tree nodes, which are destroyed between each
297 procedure Add_Char_To_Name_Buffer
(C
: Character);
298 pragma Inline
(Add_Char_To_Name_Buffer
);
299 -- Add given character to the end of the string currently stored in the
300 -- Name_Buffer, incrementing Name_Len.
302 procedure Add_Nat_To_Name_Buffer
(V
: Nat
);
303 -- Add decimal representation of given value to the end of the string
304 -- currently stored in Name_Buffer, incrementing Name_Len as required.
306 procedure Add_Str_To_Name_Buffer
(S
: String);
307 -- Add characters of string S to the end of the string currently stored
308 -- in the Name_Buffer, incrementing Name_Len by the length of the string.
310 procedure Set_Character_Literal_Name
(C
: Char_Code
);
311 -- This procedure sets the proper encoded name for the character literal
312 -- for the given character code. On return Name_Buffer and Name_Len are
313 -- set to reflect the stored name.
315 procedure Set_Name_Table_Info
(Id
: Name_Id
; Val
: Int
);
316 pragma Inline
(Set_Name_Table_Info
);
317 -- Sets the Int value associated with the given name
319 procedure Set_Name_Table_Byte
(Id
: Name_Id
; Val
: Byte
);
320 pragma Inline
(Set_Name_Table_Byte
);
321 -- Sets the Byte value associated with the given name
323 procedure Store_Encoded_Character
(C
: Char_Code
);
324 -- Stores given character code at the end of Name_Buffer, updating the
325 -- value in Name_Len appropriately. Lower case letters and digits are
326 -- stored unchanged. Other 8-bit characters are stored using the Uhh
327 -- encoding (hh = hex code), and other 16-bit wide-character values
328 -- are stored using the Whhhh (hhhh = hex code) encoding. Note that
329 -- this procedure does not fold upper case letters (they are stored
330 -- using the Uhh encoding). If folding is required, it must be done
331 -- by the caller prior to the call.
334 -- Initializes internal tables from current tree file using Tree_Read.
335 -- Note that Initialize should not be called if Tree_Read is used.
336 -- Tree_Read includes all necessary initialization.
338 procedure Tree_Write
;
339 -- Writes out internal tables to current tree file using Tree_Write
341 procedure Get_Last_Two_Chars
(N
: Name_Id
; C1
, C2
: out Character);
342 -- Obtains last two characters of a name. C1 is last but one character
343 -- and C2 is last character. If name is less than two characters long,
344 -- then both C1 and C2 are set to ASCII.NUL on return.
346 procedure Write_Name
(Id
: Name_Id
);
347 -- Write_Name writes the characters of the specified name using the
348 -- standard output procedures in package Output. No end of line is
349 -- written, just the characters of the name. On return Name_Buffer and
350 -- Name_Len are set as for a call to Get_Name_String. The name is written
351 -- in encoded form (i.e. including Uhh, Whhh, Qx, _op as they appear in
352 -- the name table). If Id is Error_Name, or No_Name, no text is output.
354 procedure wn
(Id
: Name_Id
);
355 pragma Export
(Ada
, wn
);
356 -- Like Write_Name, but includes new line at end. Intended for use
357 -- from the debugger only.
359 procedure Write_Name_Decoded
(Id
: Name_Id
);
360 -- Like Write_Name, except that the name written is the decoded name, as
361 -- described for Get_Decoded_Name_String, and the resulting value stored
362 -- in Name_Len and Name_Buffer is the decoded name.
364 ---------------------------
365 -- Table Data Structures --
366 ---------------------------
368 -- The following declarations define the data structures used to store
369 -- names. The definitions are in the private part of the package spec,
370 -- rather than the body, since they are referenced directly by gigi.
374 -- This table stores the actual string names. Although logically there
375 -- is no need for a terminating character (since the length is stored
376 -- in the name entry table), we still store a NUL character at the end
377 -- of every name (for convenience in interfacing to the C world).
379 package Name_Chars
is new Table
.Table
(
380 Table_Component_Type
=> Character,
381 Table_Index_Type
=> Int
,
382 Table_Low_Bound
=> 0,
383 Table_Initial
=> Alloc
.Name_Chars_Initial
,
384 Table_Increment
=> Alloc
.Name_Chars_Increment
,
385 Table_Name
=> "Name_Chars");
387 type Name_Entry
is record
388 Name_Chars_Index
: Int
;
389 -- Starting location of characters in the Name_Chars table minus
390 -- one (i.e. pointer to character just before first character). The
391 -- reason for the bias of one is that indexes in Name_Buffer are
392 -- one's origin, so this avoids unnecessary adds and subtracts of 1.
395 -- Length of this name in characters
398 -- Byte value associated with this name
401 -- Link to next entry in names table for same hash code
404 -- Int Value associated with this name
407 -- This is the table that is referenced by Name_Id entries.
408 -- It contains one entry for each unique name in the table.
410 package Name_Entries
is new Table
.Table
(
411 Table_Component_Type
=> Name_Entry
,
412 Table_Index_Type
=> Name_Id
,
413 Table_Low_Bound
=> First_Name_Id
,
414 Table_Initial
=> Alloc
.Names_Initial
,
415 Table_Increment
=> Alloc
.Names_Increment
,
416 Table_Name
=> "Name_Entries");