1------------------------------------------------------------------------------
2--                                                                          --
3--                        GNAAMP COMPILER COMPONENTS                        --
4--                                                                          --
5--                              A A _ U T I L                               --
6--                                                                          --
7--                                 S p e c                                  --
8--                                                                          --
9--                     Copyright (C) 2001-2011, AdaCore                     --
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.  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 COPYING3.  If not, go to --
19-- http://www.gnu.org/licenses for a complete copy of the license.          --
20--                                                                          --
21------------------------------------------------------------------------------
22
23--  This package provides various utility operations used by GNAT back-ends
24--  (e.g. AAMP).
25
26--  This package is a messy grab bag of stuff. These routines should be moved
27--  to appropriate units (sem_util,sem_aux,exp_util,namet,uintp,urealp). ???
28
29with Namet;  use Namet;
30with Types;  use Types;
31with Uintp;  use Uintp;
32with Urealp; use Urealp;
33
34package AA_Util is
35
36   function Is_Global_Entity (E : Entity_Id) return Boolean;
37   --  Returns true if and only if E is a library-level entity (excludes
38   --  entities declared within blocks at the outer level of library packages).
39
40   function New_Name_Id (Name : String) return Name_Id;
41   --  Returns a Name_Id corresponding to the given name string
42
43   function Name_String (Name : Name_Id) return String;
44   --  Returns the name string associated with Name
45
46   function New_String_Id (S : String) return String_Id;
47   --  Returns a String_Id corresponding to the given string
48
49   function String_Value (Str_Id : String_Id) return String;
50   --  Returns the string associated with Str_Id
51
52   --  Name-generation utilities
53
54   type Name_Sequencer is private;
55   --  This type is used to support back-end generation of unique symbol
56   --  (e.g., for string literal objects or labels). By declaring an
57   --  aliased object of type Name_Sequence and passing that object
58   --  to the function Next_Name, a series of names with suffixes
59   --  of the form "__n" will be produced, where n is a string denoting
60   --  a positive integer.  The sequence starts with "__1", and increases
61   --  by one on each successive call to Next_Name for a given Name_Sequencer.
62
63   function Next_Name
64     (Name_Seq    : not null access Name_Sequencer;
65      Name_Prefix : String) return Name_Id;
66   --  Returns the Name_Id for a name composed of the given Name_Prefix
67   --  concatentated with a unique number suffix of the form "__n",
68   --  as detemined by the current state of Name_Seq.
69
70   function Elab_Spec_Name (Module_Name : Name_Id) return Name_Id;
71   --  Returns a name id for the elaboration subprogram to be associated with
72   --  the specification of the named module. The denoted name is of the form
73   --  "modulename___elabs".
74
75   function Elab_Body_Name (Module_Name : Name_Id) return Name_Id;
76   --  Returns a name id for the elaboration subprogram to be associated
77   --  with the body of the named module. The denoted name is of the form
78   --  "modulename___elabb".
79
80   function File_Name_Without_Suffix (File_Name : String) return String;
81   --  Removes the suffix ('.' followed by other characters), if present, from
82   --  the end of File_Name and returns the shortened name (otherwise simply
83   --  returns File_Name).
84
85   function Source_Name (Sloc : Source_Ptr) return File_Name_Type;
86   --  Returns file name corresponding to the source file name associated with
87   --  the given source position Sloc.
88
89   function Source_Name_Without_Suffix (Sloc : Source_Ptr) return String;
90   --  Returns a string corresponding to the source file name associated with
91   --  the given source position Sloc, with its dot-preceded suffix, if any,
92   --  removed. As examples, the name "main.adb" is mapped to "main" and the
93   --  name "main.2.ada" is mapped to "main.2". As a special case, file names
94   --  with a ".dg" suffix will also strip off the ".dg", so "main.adb.dg"
95   --  becomes simply "main".
96
97   function Source_Id_String (Unit_Name : Name_Id) return String;
98   --  Returns a string that uniquely identifies the unit with the given
99   --  Unit_Name. This string is derived from Unit_Name by replacing any
100   --  multiple underscores with dot ('.') characters and normalizing the
101   --  casing to mixed case (e.g., "ada__strings" is mapped to ("Ada.Strings").
102
103   function Source_Id (Unit_Name : Name_Id) return String_Id;
104   --  Returns a String_Id reference to a string that uniquely identifies
105   --  the program unit having the given name (as defined for function
106   --  Source_Id_String).
107
108   function Source_Id_String (Sloc : Source_Ptr) return String;
109   --  Returns a string that uniquely identifies the source file containing
110   --  the given source location.  This string is constructed from the
111   --  concatentation of the date and time stamp of the file with a
112   --  hexadecimal check sum (e.g., "020425143059ABCDEF01").
113
114   function Source_Id (Sloc : Source_Ptr) return String_Id;
115   --  Returns a String_Id reference to a string that uniquely identifies the
116   --  source file containing the given source location (as defined for
117   --  function Source_Id_String).
118
119   function Image (I : Int) return String;
120   --  Returns Int'Image (I), but without a leading space in the case where
121   --  I is nonnegative. Useful for concatenating integers onto other names.
122
123   type Integer_Image_Format is (Decimal, Ada_Hex, AAMP_Hex);
124
125   function UI_Image (I : Uint; Format : Integer_Image_Format) return String;
126   --  Returns the image of the universal integer I, with no leading spaces
127   --  and in the format specified. The Format parameter specifies whether
128   --  the integer representation should be decimal (the default), or Ada
129   --  hexadecimal (Ada_Hex => "16#xxxxx#" format), or AAMP hexadecimal.
130   --  In the latter case, the integer will have the form of a sequence of
131   --  hexadecimal digits bracketed by '^' characters, and will contain '_'
132   --  characters as separators for groups of four hexadecimal digits
133   --  (e.g., ^1C_A3CD^). If the format AAMP_Hex is selected, the universal
134   --  integer must have a nonnegative value.
135
136   function UR_Image (R : Ureal) return String;
137   --  Returns a decimal image of the universal real value R
138
139private
140
141   type Name_Sequencer is record
142      Sequence_Number : Natural := 0;
143   end record;
144
145end AA_Util;
146