diff options
Diffstat (limited to 'gcc/ada/namet.ads')
| -rw-r--r-- | gcc/ada/namet.ads | 400 |
1 files changed, 400 insertions, 0 deletions
diff --git a/gcc/ada/namet.ads b/gcc/ada/namet.ads new file mode 100644 index 00000000000..2517c5579a3 --- /dev/null +++ b/gcc/ada/namet.ads @@ -0,0 +1,400 @@ +------------------------------------------------------------------------------ +-- -- +-- GNAT COMPILER COMPONENTS -- +-- -- +-- N A M E T -- +-- -- +-- S p e c -- +-- -- +-- $Revision: 1.78 $ +-- -- +-- Copyright (C) 1992-2001 Free Software Foundation, Inc. -- +-- -- +-- GNAT is free software; you can redistribute it and/or modify it under -- +-- terms of the GNU General Public License as published by the Free Soft- -- +-- ware Foundation; either version 2, or (at your option) any later ver- -- +-- sion. GNAT is distributed in the hope that it will be useful, but WITH- -- +-- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY -- +-- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -- +-- for more details. You should have received a copy of the GNU General -- +-- Public License distributed with GNAT; see file COPYING. If not, write -- +-- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, -- +-- MA 02111-1307, USA. -- +-- -- +-- As a special exception, if other files instantiate generics from this -- +-- unit, or you link this unit with other files to produce an executable, -- +-- this unit does not by itself cause the resulting executable to be -- +-- covered by the GNU General Public License. This exception does not -- +-- however invalidate any other reasons why the executable file might be -- +-- covered by the GNU Public License. -- +-- -- +-- GNAT was originally developed by the GNAT team at New York University. -- +-- It is now maintained by Ada Core Technologies Inc (http://www.gnat.com). -- +-- -- +------------------------------------------------------------------------------ + +with Alloc; +with Table; +with System; use System; +with Types; use Types; + +package Namet is + +-- WARNING: There is a C version of this package. Any changes to this +-- source file must be properly reflected in the C header file namet.h +-- which is created manually from namet.ads and namet.adb. + +-- This package contains routines for handling the names table. The table +-- is used to store character strings for identifiers and operator symbols, +-- as well as other string values such as unit names and file names. + +-- The forms of the entries are as follows: + +-- Identifiers Stored with upper case letters folded to lower case. +-- Upper half (16#80# bit set) and wide characters are +-- stored in an encoded form (Uhh for upper half and +-- Whhhh for wide characters, as provided by the routine +-- Store_Encoded_Character, where hh are hex digits for +-- the character code using lower case a-f). Other +-- internally generated names use upper case letters +-- (other than O,Q,U,W) to ensure that they do not clash +-- with identifier names in the source program. + +-- Operator symbols Stored with an initial letter O, and the remainder +-- of the name is the lower case characters XXX where +-- the name is Name_Op_XXX, see Snames spec for a full +-- list of the operator names. + +-- Character literals Character literals have names that are used only for +-- debugging and error message purposes. The form is a +-- upper case Q followed by a single letter, or by a Uxx +-- or Wxxxx encoding as described for identifiers. The +-- Set_Character_Literal_Name procedure should be used +-- to construct these encodings. + +-- Unit names Stored with upper case letters folded to lower case, +-- using Uhh/Whhhh encoding as described for identifiers, +-- and a %s or %b suffix for specs/bodies. See package +-- Uname for further details. + +-- File names Are stored in the form provided by Osint. Typically +-- they may include wide character escape sequences and +-- upper case characters (in non-encoded form). Casing +-- is also derived from the external environment. Note +-- that file names provided by Osint must generally be +-- consistent with the names from Fname.Get_File_Name. + +-- Other strings The names table is also used as a convenient storage +-- location for other variable length strings such as +-- error messages etc. There are no restrictions on what +-- characters may appear for such entries. + +-- Note: the encodings Uhh (upper half characters), Whhhh (wide characters), +-- and Qx (character literal names) are described in the spec, since they +-- are visible throughout the system (e.g. in debugging output). However, +-- no code should depend on these particular encodings, so it should be +-- possible to change the encodings by making changes only to the Namet +-- specification (to change these comments) and the body (which actually +-- implements the encodings). + +-- The names are hashed so that a given name appears only once in the table, +-- except that names entered with Name_Enter as opposed to Name_Find are +-- omitted from the hash table. + +-- The first 26 entries in the names table (with Name_Id values in the range +-- First_Name_Id .. First_Name_Id + 25) represent names which are the one +-- character lower case letters in the range a-z, and these names are created +-- and initialized by the Initialize procedure. + +-- Two values, one of type Int and one of type Byte, are stored with each +-- names table entry and subprograms are provided for setting and retrieving +-- these associated values. The usage of these values is up to the client. +-- In the compiler, the Int field is used to point to a chain of potentially +-- visible entities (see Sem.Ch8 for details), and the Byte field is used +-- to hold the Token_Type value for reserved words (see Sem for details). +-- In the binder, the Byte field is unused, and the Int field is used in +-- various ways depending on the name involved (see binder documentation). + + Name_Buffer : String (1 .. 16*1024); + -- This buffer is used to set the name to be stored in the table for the + -- Name_Find call, and to retrieve the name for the Get_Name_String call. + -- The plus 1 in the length allows for cases of adding ASCII.NUL. The + -- 16K here is intended to be an infinite value that ensures that we + -- never overflow the buffer (names this long are too absurd to worry!) + + Name_Len : Natural; + -- Length of name stored in Name_Buffer. Used as an input parameter for + -- Name_Find, and as an output value by Get_Name_String, or Write_Name. + + ----------------- + -- Subprograms -- + ----------------- + + procedure Finalize; + -- Called at the end of a use of the Namet package (before a subsequent + -- call to Initialize). Currently this routine is only used to generate + -- debugging output. + + procedure Get_Name_String (Id : Name_Id); + -- Get_Name_String is used to retrieve the string associated with an entry + -- in the names table. The resulting string is stored in Name_Buffer + -- and Name_Len is set. It is an error to call Get_Name_String with one + -- of the special name Id values (No_Name or Error_Name). + + function Get_Name_String (Id : Name_Id) return String; + -- This functional form returns the result as a string without affecting + -- the contents of either Name_Buffer or Name_Len. + + procedure Get_Unqualified_Name_String (Id : Name_Id); + -- Similar to the above except that qualification (as defined in unit + -- Exp_Dbug) is removed (including both preceding __ delimited names, + -- and also the suffix used to indicate package body entities). Note + -- that names are not qualified until just before the call to gigi, so + -- this routine is only needed by processing that occurs after gigi has + -- been called. This includes all ASIS processing, since ASIS works on + -- the tree written after gigi has been called. + + procedure Get_Name_String_And_Append (Id : Name_Id); + -- Like Get_Name_String but the resulting characters are appended to + -- the current contents of the entry stored in Name_Buffer, and Name_Len + -- is incremented to include the added characters. + + procedure Get_Decoded_Name_String (Id : Name_Id); + -- Same calling sequence an interface as Get_Name_String, except that the + -- result is decoded, so that upper half characters and wide characters + -- appear as originally found in the source program text, operators have + -- their source forms (special characters and enclosed in quotes), and + -- character literals appear surrounded by apostrophes. + + procedure Get_Unqualified_Decoded_Name_String (Id : Name_Id); + -- Similar to the above except that qualification (as defined in unit + -- Exp_Dbug) is removed (including both preceding __ delimited names, + -- and also the suffix used to indicate package body entities). Note + -- that names are not qualified until just before the call to gigi, so + -- this routine is only needed by processing that occurs after gigi has + -- been called. This includes all ASIS processing, since ASIS works on + -- the tree written after gigi has been called. + + procedure Get_Decoded_Name_String_With_Brackets (Id : Name_Id); + -- This routine is similar to Decoded_Name, except that the brackets + -- notation (Uhh replaced by ["hh"], Whhhh replaced by ["hhhh"]) is + -- used for all non-lower half characters, regardless of the setting + -- of Opt.Wide_Character_Encoding_Method, and also in that characters + -- in the range 16#80# .. 16#FF# are converted to brackets notation + -- in all cases. This routine can be used when there is a requirement + -- for a canonical representation not affected by the character set + -- options (e.g. in the binder generation of symbols). + + function Get_Name_Table_Byte (Id : Name_Id) return Byte; + pragma Inline (Get_Name_Table_Byte); + -- Fetches the Byte value associated with the given name + + function Get_Name_Table_Info (Id : Name_Id) return Int; + pragma Inline (Get_Name_Table_Info); + -- Fetches the Int value associated with the given name + + procedure Initialize; + -- Initializes the names table, including initializing the first 26 + -- entries in the table (for the 1-character lower case names a-z) + -- Note that Initialize must not be called if Tree_Read is used. + + procedure Lock; + -- Lock name table before calling back end. Space for up to 10 extra + -- names and 1000 extra characters is reserved before the table is locked. + + procedure Unlock; + -- Unlocks the name table to allow use of the 10 extra names and 1000 + -- extra characters reserved by the Lock call. See gnat1drv for details + -- of the need for this. + + function Length_Of_Name (Id : Name_Id) return Nat; + pragma Inline (Length_Of_Name); + -- Returns length of given name in characters. This is the length of the + -- encoded name, as stored in the names table, the result is equivalent to + -- calling Get_Name_String and reading Name_Len, except that a call to + -- Length_Of_Name does not affect the contents of Name_Len and Name_Buffer. + + function Name_Chars_Address return System.Address; + -- Return starting address of name characters table (used in Back_End + -- call to Gigi). + + function Name_Find return Name_Id; + -- Name_Find is called with a string stored in Name_Buffer whose length + -- is in Name_Len (i.e. the characters of the name are in subscript + -- positions 1 to Name_Len in Name_Buffer). It searches the names + -- table to see if the string has already been stored. If so the Id of + -- the existing entry is returned. Otherwise a new entry is created with + -- its Name_Table_Info field set to zero. The contents of Name_Buffer + -- and Name_Len are not modified by this call. + + function Name_Enter return Name_Id; + -- Name_Enter has the same calling interface as Name_Find. The difference + -- is that it does not search the table for an existing match, and also + -- subsequent Name_Find calls using the same name will not locate the + -- entry created by this call. Thus multiple calls to Name_Enter with the + -- same name will create multiple entries in the name table with different + -- Name_Id values. This is useful in the case of created names, which are + -- never expected to be looked up. Note: Name_Enter should never be used + -- for one character names, since these are efficiently located without + -- hashing by Name_Find in any case. + + function Name_Entries_Address return System.Address; + -- Return starting address of Names table. Used in Back_End call to Gigi. + + function Name_Entries_Count return Nat; + -- Return current number of entries in the names table + + function Is_OK_Internal_Letter (C : Character) return Boolean; + pragma Inline (Is_OK_Internal_Letter); + -- Returns true if C is a suitable character for using as a prefix or a + -- suffix of an internally generated name, i.e. it is an upper case letter + -- other than one of the ones used for encoding source names (currently + -- the set of reserved letters is O, Q, U, W) and also returns False for + -- the letter X, which is reserved for debug output (see Exp_Dbug). + + function Is_Internal_Name (Id : Name_Id) return Boolean; + -- Returns True if the name is an internal name (i.e. contains a character + -- for which Is_OK_Internal_Letter is true, or if the name starts or ends + -- with an underscore. This call destroys the value of Name_Len and + -- Name_Buffer (it loads these as for Get_Name_String). + -- + -- Note: if the name is qualified (has a double underscore), then + -- only the final entity name is considered, not the qualifying + -- names. Consider for example that the name: + -- + -- pkg__B_1__xyz + -- + -- is not an internal name, because the B comes from the internal + -- name of a qualifying block, but the xyz means that this was + -- indeed a declared identifier called "xyz" within this block + -- and there is nothing internal about that name. + + function Is_Internal_Name return Boolean; + -- Like the form with an Id argument, except that the name to be tested is + -- passed in Name_Buffer and Name_Len (which are not affected by the call). + -- Name_Buffer (it loads these as for Get_Name_String). + + procedure Reset_Name_Table; + -- This procedure is used when there are multiple source files to reset + -- the name table info entries associated with current entries in the + -- names table. There is no harm in keeping the names entries themselves + -- from one compilation to another, but we can't keep the entity info, + -- since this refers to tree nodes, which are destroyed between each + -- main source file. + + procedure Add_Char_To_Name_Buffer (C : Character); + pragma Inline (Add_Char_To_Name_Buffer); + -- Add given character to the end of the string currently stored in the + -- Name_Buffer, incrementing Name_Len. + + procedure Add_Nat_To_Name_Buffer (V : Nat); + -- Add decimal representation of given value to the end of the string + -- currently stored in Name_Buffer, incrementing Name_Len as required. + + procedure Add_Str_To_Name_Buffer (S : String); + -- Add characters of string S to the end of the string currently stored + -- in the Name_Buffer, incrementing Name_Len by the length of the string. + + procedure Set_Character_Literal_Name (C : Char_Code); + -- This procedure sets the proper encoded name for the character literal + -- for the given character code. On return Name_Buffer and Name_Len are + -- set to reflect the stored name. + + procedure Set_Name_Table_Info (Id : Name_Id; Val : Int); + pragma Inline (Set_Name_Table_Info); + -- Sets the Int value associated with the given name + + procedure Set_Name_Table_Byte (Id : Name_Id; Val : Byte); + pragma Inline (Set_Name_Table_Byte); + -- Sets the Byte value associated with the given name + + procedure Store_Encoded_Character (C : Char_Code); + -- Stores given character code at the end of Name_Buffer, updating the + -- value in Name_Len appropriately. Lower case letters and digits are + -- stored unchanged. Other 8-bit characters are stored using the Uhh + -- encoding (hh = hex code), and other 16-bit wide-character values + -- are stored using the Whhhh (hhhh = hex code) encoding. Note that + -- this procedure does not fold upper case letters (they are stored + -- using the Uhh encoding). If folding is required, it must be done + -- by the caller prior to the call. + + procedure Tree_Read; + -- Initializes internal tables from current tree file using Tree_Read. + -- Note that Initialize should not be called if Tree_Read is used. + -- Tree_Read includes all necessary initialization. + + procedure Tree_Write; + -- Writes out internal tables to current tree file using Tree_Write + + procedure Write_Name (Id : Name_Id); + -- Write_Name writes the characters of the specified name using the + -- standard output procedures in package Output. No end of line is + -- written, just the characters of the name. On return Name_Buffer and + -- Name_Len are set as for a call to Get_Name_String. The name is written + -- in encoded form (i.e. including Uhh, Whhh, Qx, _op as they appear in + -- the name table). If Id is Error_Name, or No_Name, no text is output. + + procedure wn (Id : Name_Id); + -- Like Write_Name, but includes new line at end. Intended for use + -- from the debugger only. + + procedure Write_Name_Decoded (Id : Name_Id); + -- Like Write_Name, except that the name written is the decoded name, as + -- described for Get_Name_Decoded, and the resulting value stored in + -- Name_Len and Name_Buffer is the decoded name. + + --------------------------- + -- Table Data Structures -- + --------------------------- + + -- The following declarations define the data structures used to store + -- names. The definitions are in the private part of the package spec, + -- rather than the body, since they are referenced directly by gigi. + +private + + -- This table stores the actual string names. Although logically there + -- is no need for a terminating character (since the length is stored + -- in the name entry table), we still store a NUL character at the end + -- of every name (for convenience in interfacing to the C world). + + package Name_Chars is new Table.Table ( + Table_Component_Type => Character, + Table_Index_Type => Int, + Table_Low_Bound => 0, + Table_Initial => Alloc.Name_Chars_Initial, + Table_Increment => Alloc.Name_Chars_Increment, + Table_Name => "Name_Chars"); + + type Name_Entry is record + Name_Chars_Index : Int; + -- Starting location of characters in the Name_Chars table minus + -- one (i.e. pointer to character just before first character). The + -- reason for the bias of one is that indexes in Name_Buffer are + -- one's origin, so this avoids unnecessary adds and subtracts of 1. + + Name_Len : Short; + -- Length of this name in characters + + Byte_Info : Byte; + -- Byte value associated with this name + + Hash_Link : Name_Id; + -- Link to next entry in names table for same hash code + + Int_Info : Int; + -- Int Value associated with this name + end record; + + -- This is the table that is referenced by Name_Id entries. + -- It contains one entry for each unique name in the table. + + package Name_Entries is new Table.Table ( + Table_Component_Type => Name_Entry, + Table_Index_Type => Name_Id, + Table_Low_Bound => First_Name_Id, + Table_Initial => Alloc.Names_Initial, + Table_Increment => Alloc.Names_Increment, + Table_Name => "Name_Entries"); + +end Namet; |