From 523792edaef032f41ea8a0bb8273013ced2a9276 Mon Sep 17 00:00:00 2001 From: Tristan Gingold Date: Wed, 24 Dec 2014 12:19:17 +0100 Subject: name_table: add comments. --- src/name_table.ads | 62 +++++++++++++++++++++++++++--------------------------- 1 file changed, 31 insertions(+), 31 deletions(-) (limited to 'src/name_table.ads') diff --git a/src/name_table.ads b/src/name_table.ads index c3d3e72f1..c5b6b9cb4 100644 --- a/src/name_table.ads +++ b/src/name_table.ads @@ -18,42 +18,42 @@ with System; with Types; use Types; --- A very simple name table. --- This is an hash table, such as id1=id2 <=> get_string(id1)=get_string(id2). +-- A very simple name table. This is an hash table, so that +-- id1 = id2 <=> get_string (id1) = get_string (id2). package Name_Table is - -- Initialize the package, ie create tables. + -- Initialize the package, ie create tables. procedure Initialize; - -- Get an entry in the name table. - -- (entries for characters are already built). + -- Get an entry in the name table for a character. + -- (entries for characters are already built). Characters are put in the + -- name table, but are always different from identifiers. They simply + -- share the same Name_Id type. function Get_Identifier (Char: Character) return Name_Id; pragma Inline (Get_Identifier); - -- Get or create an entry in the name table. - -- If an entry is created, its token value is tok_identifier. - -- Note: - -- an identifier is represented in all lower case letter, - -- an extended identifier is represented in backslashes, double internal - -- backslashes are simplified, - -- a string is represented by its contents (without the quotation - -- characters, and simplified), - -- a bit string is represented by its raw contents (no simplification). + -- Get or create an entry in the name table. Note: + -- * an identifier is represented in all lower case letter, + -- * an extended identifier is represented in backslashes, double internal + -- backslashes are simplified. function Get_Identifier (Str: String) return Name_Id; - -- Get the string associed to a name. - -- If the name is a character, then single quote are added. + -- Get the string associed to a name. + -- If the name is a character, then single quote are added. function Image (Id: Name_Id) return String; - -- Get the address of the first character of ID. - -- The string is NUL-terminated (this is done by get_identifier). + -- Get the address of the first character of ID. The address is valid + -- until the next call to Get_Identifier (which may reallocate the string + -- table). + -- The string is NUL-terminated (this is done by get_identifier). function Get_Address (Id: Name_Id) return System.Address; - -- Get the length of ID. + -- Get the length of ID. function Get_Name_Length (Id: Name_Id) return Natural; pragma Inline (Get_Name_Length); - -- Get the character associed to a name. + -- Get the character associed to a name. This is valid only for character + -- ids. function Get_Character (Id: Name_Id) return Character; pragma Inline (Get_Character); @@ -61,35 +61,35 @@ package Name_Table is function Is_Character (Id: Name_Id) return Boolean; pragma Inline (Is_Character); - -- Get or create an entry in the name table, use NAME_BUFFER/NAME_LENGTH. + -- Get or create an entry in the name table, use NAME_BUFFER/NAME_LENGTH. function Get_Identifier return Name_Id; -- Like GET_IDENTIFIER, but return NULL_IDENTIFIER if the identifier -- is not found (and do not create an entry for it). function Get_Identifier_No_Create return Name_Id; - -- Set NAME_BUFFER/NAME_LENGTH with the image of ID. + -- Set NAME_BUFFER/NAME_LENGTH with the image of ID. Characters aren't + -- quoted. procedure Image (Id : Name_Id); - -- Get and set the info field associated with each identifier. - -- Used to store interpretations of the name. + -- Get and set the info field associated with each identifier. + -- Used to store interpretations of the name. function Get_Info (Id: Name_Id) return Int32; pragma Inline (Get_Info); procedure Set_Info (Id: Name_Id; Info: Int32); pragma Inline (Set_Info); - -- Return the latest name_id used. - -- kludge, use only for debugging. + -- Return the latest name_id used. This is only for debugging or stats. function Last_Name_Id return Name_Id; - -- Be sure all info fields have their default value. + -- Be sure all info fields have their default value. procedure Assert_No_Infos; - -- This buffer is used by get_token to set the name. - -- This can be seen as a copy buffer but this is necessary for two reasons: - -- names case must be 'normalized', because VHDL is case insensitive. + -- This buffer is used by get_token to set the name. + -- This can be seen as a copy buffer but this is necessary for two reasons: + -- names case must be 'normalized', because VHDL is case insensitive. Name_Buffer : String (1 .. 1024); - -- The length of the name string. + -- The length of the name string. Name_Length: Natural; -- Disp statistics. -- cgit v1.2.3