1
------------------------------------------------------------------------------
3
-- ASIS-for-GNAT IMPLEMENTATION COMPONENTS --
5
-- A S I S . A D A _ E N V I R O N M E N T S --
10
-- This specification is adapted from the Ada Semantic Interface --
11
-- Specification (ASIS) definition, ISO/IEC 15291, Working Draft. In --
12
-- accordance with the (expected) copyright of the ASIS definition, you can --
13
-- freely copy and modify this specification, provided that if you --
14
-- redistribute a modified version, any changes that you have made are --
15
-- clearly indicated. --
17
------------------------------------------------------------------------------
19
-- The content of this specification is taken "as is" from ASIS 2.0.R.
20
-- The code is reformatted to follow the GNAT coding style rules.
22
------------------------------------------------------------------------------
23
-- 8 package Asis.Ada_Environments
24
------------------------------------------------------------------------------
25
------------------------------------------------------------------------------
26
package Asis.Ada_Environments is
27
------------------------------------------------------------------------------
28
------------------------------------------------------------------------------
29
-- Asis.Ada_Environments encapsulates a set of queries that map physical Ada
30
-- compilation and program execution environments to logical ASIS
33
------------------------------------------------------------------------------
34
-- 8.1 function Default_Name
35
------------------------------------------------------------------------------
37
function Default_Name return Wide_String;
39
------------------------------------------------------------------------------
40
-- Returns the default context name. If there is no default context name, a
41
-- null string is returned.
43
------------------------------------------------------------------------------
44
-- 8.2 function Default_Parameters
45
------------------------------------------------------------------------------
47
function Default_Parameters return Wide_String;
49
------------------------------------------------------------------------------
50
-- Returns the default context parameters. If there are no default context
51
-- parameters, a null string is returned.
53
------------------------------------------------------------------------------
54
-- 8.3 procedure Associate
55
------------------------------------------------------------------------------
58
(The_Context : in out Asis.Context;
59
Name : in Wide_String;
60
Parameters : in Wide_String := Default_Parameters);
62
------------------------------------------------------------------------------
63
-- The_Context - Specifies the Context to associate
64
-- Name - Specifies the name for the Context association
65
-- Parameters - Specifies parameters to use when opening the Context
67
-- Used to give name and parameter associations to a Context. The
68
-- Has_Associations query is used to test whether or not a Context has
69
-- been given name and parameter associations. The Name and Parameters
70
-- queries are used to examine name and parameter associations.
72
-- A Context has at most one set of name/parameter values associated with
73
-- it at any time. Name and parameter associations cannot be modified while a
74
-- Context is open Previous name and parameters associations for this Context
75
-- are replaced by this call.
77
-- ASIS implementations are encouraged, but not required, to validate the
78
-- Parameters string immediately. It is recognized that some options cannot
79
-- be completely validated until the Open is performed. An invalid Parameters
80
-- value is reported by raising ASIS_Failed with a Status of Parameter_Error.
82
-- Raises ASIS_Inappropriate_Context if The_Context is open.
84
------------------------------------------------------------------------------
86
------------------------------------------------------------------------------
88
procedure Open (The_Context : in out Asis.Context);
90
------------------------------------------------------------------------------
91
-- The_Context - Specifies the Context to open
93
-- Opens the ASIS Context using the Context's associated name and parameter
96
-- Raises ASIS_Inappropriate_Context if The_Context is already open or if it
97
-- is uninitialized (does not have associated name and parameter values).
99
-- Raises ASIS_Failed if The_Context could not be opened for any reason. The
100
-- most likely Status values are Name_Error, Use_Error, Data_Error, and
101
-- Parameter_Error. Other possibilities include Storage_Error and
104
------------------------------------------------------------------------------
105
-- 8.5 procedure Close
106
------------------------------------------------------------------------------
108
procedure Close (The_Context : in out Asis.Context);
110
------------------------------------------------------------------------------
111
-- The_Context - Specifies the Context to close
113
-- Closes the ASIS Context. Any previous Context name and parameter
114
-- associations are retained. This allows the same Context to be re-opened
115
-- later with the same associations.
117
-- All Compilation_Unit and Element values obtained from The_Context become
118
-- invalid when it is closed. Subsequent calls to ASIS services using such
119
-- invalid Compilation_Unit or Element values are erroneous. ASIS
120
-- implementations will attempt to detect such usage and raise ASIS_Failed in
121
-- response. Applications should be aware that the ability to detect the use
122
-- of such "dangling references" is implementation specific and not all
123
-- implementations are able to raise ASIS_Failed at the appropriate
124
-- points. Thus, applications that attempt to utilize invalid values may
125
-- exhibit unpredictable behavior.
127
-- Raises ASIS_Inappropriate_Context if The_Context is not open.
129
------------------------------------------------------------------------------
130
-- 8.6 procedure Dissociate
131
------------------------------------------------------------------------------
133
procedure Dissociate (The_Context : in out Asis.Context);
135
------------------------------------------------------------------------------
136
-- The_Context - Specifies the Context whose name and parameter associations
139
-- Severs all previous associations for The_Context. A Context that does not
140
-- have associations (is uninitialized) is returned unchanged. The
141
-- variable The_Context is returned to its uninitialized state.
143
-- Contexts that have been given Names and Parameters should be Dissociated
144
-- when they are no longer necessary. Some amount of program storage can be
145
-- tied up by the stored Name and Parameter strings. This space is only
146
-- freed when a Context is Dissociated or when ASIS is Finalized.
148
-- This operation has no physical affect on any implementor's Ada environment.
150
-- Raises ASIS_Inappropriate_Context if The_Context is open.
152
------------------------------------------------------------------------------
153
-- 8.7 function Is_Equal
154
------------------------------------------------------------------------------
157
(Left : in Asis.Context;
158
Right : in Asis.Context)
161
------------------------------------------------------------------------------
162
-- Left - Specifies the first Context
163
-- Right - Specifies the second Context
165
-- Returns True if Left and Right designate the same set of associated
166
-- compilation units. The Context variables may be open or closed.
168
-- Unless both Contexts are open, this operation is implemented as a pair of
169
-- simple string comparisons between the Name and Parameter associations for
170
-- the two Contexts. If both Contexts are open, this operation acts as a
171
-- set comparison and returns True if both sets contain the same units (all
172
-- unit versions are included in the comparison).
174
-- --|AN Application Note:
176
-- --|AN With some implementations, Is_Equal may be True before the Contexts
177
-- --|AN are opened, but may be False after the Contexts are open.
178
-- --|AN One possible cause for this is a sequence of events such as:
180
-- --|AN 1) ASIS program A opens the Left Context for READ,
181
-- --|AN 2) non-ASIS program B opens the Context for UPDATE, and creates
182
-- --|AN a new version of the implementor Context,
183
-- --|AN 3) ASIS program A opens the Right Context for READ, and gets the
184
-- --|AN new version.
186
------------------------------------------------------------------------------
187
-- 8.8 function Is_Identical
188
------------------------------------------------------------------------------
190
function Is_Identical
191
(Left : in Asis.Context;
192
Right : in Asis.Context)
195
------------------------------------------------------------------------------
196
-- Left - Specifies the first Context
197
-- Right - Specifies the second Context
199
-- Returns True if Left and Right both designate the value associated with
200
-- one specific ASIS Context variable.
202
-- Returns False otherwise or if either Context is not open.
204
-- --|AN Application Note:
206
-- --|AN No two physically separate open Context variables are ever
207
-- --|AN Is_Identical. The value associated with an open ASIS Context variable
208
-- --|AN is also directly associated with every Compilation_Unit or Element
209
-- --|AN derived from that Context. It is possible to obtain these Context
210
-- --|AN values by way of the Enclosing_Context and the
211
-- --|AN Enclosing_Compilation_Unit queries. These Context values can be
212
-- --|AN tested for identity with each other or with specific Context
213
-- --|AN variables. An open ASIS Context variable and an Enclosing_Context
214
-- --|AN value are only Is_Identical if the Compilation_Unit in question
215
-- --|AN was derived specifically from that open ASIS Context variable.
217
------------------------------------------------------------------------------
218
-- 8.9 function Exists
219
------------------------------------------------------------------------------
221
function Exists (The_Context : in Asis.Context) return Boolean;
223
------------------------------------------------------------------------------
224
-- The_Context - Specifies a Context with associated name and parameter values
226
-- Returns True if The_Context is open or if The_Context designates an Ada
227
-- environment that can be determined to exist.
229
-- Returns False for any uninitialized The_Context variable.
231
-- --|IP Implementation Permissions:
233
-- --|IP No guarantee is made that The_Context is readable or that an Open
234
-- --|IP operation on The_Context would succeed. The associated
235
-- --|IP parameter value for The_Context may not be fully validated by this
236
-- --|IP simple existence check. It may contain information that can only be
237
-- --|IP verified by an Open.
239
------------------------------------------------------------------------------
240
-- 8.10 function Is_Open
241
------------------------------------------------------------------------------
243
function Is_Open (The_Context : in Asis.Context) return Boolean;
245
------------------------------------------------------------------------------
246
-- The_Context - Specifies the Context to check
248
-- Returns True if The_Context is currently open.
250
------------------------------------------------------------------------------
251
-- 8.11 function Has_Associations
252
------------------------------------------------------------------------------
254
function Has_Associations (The_Context : in Asis.Context) return Boolean;
256
------------------------------------------------------------------------------
257
-- The_Context - Specifies the Context to check
259
-- Returns True if name and parameter values have been associated with
262
-- Returns False if The_Context is uninitialized.
264
------------------------------------------------------------------------------
266
------------------------------------------------------------------------------
267
-- 8.12 function Name
268
------------------------------------------------------------------------------
270
function Name (The_Context : in Asis.Context) return Wide_String;
272
------------------------------------------------------------------------------
273
-- The_Context - Specifies the Context to check
275
-- Returns the Name value associated with The_Context.
277
-- Returns a null string if The_Context is uninitialized.
279
------------------------------------------------------------------------------
280
-- 8.13 function Parameter
281
------------------------------------------------------------------------------
283
function Parameters (The_Context : in Asis.Context) return Wide_String;
285
------------------------------------------------------------------------------
286
-- The_Context - Specifies the Context to check
288
-- Returns the Parameters value associated with The_Context.
290
-- Returns a null string if The_Context is uninitialized.
292
------------------------------------------------------------------------------
293
-- 8.14 function Debug_Image
294
------------------------------------------------------------------------------
296
function Debug_Image (The_Context : in Asis.Context) return Wide_String;
298
------------------------------------------------------------------------------
299
-- The_Context - Specifies the Context to represent
301
-- Returns a string value containing implementation-defined debugging
302
-- information associated with The_Context.
304
-- The return value uses Asis.Text.Delimiter_Image to separate lines in
305
-- multi-line results. The return value is not terminated with
306
-- Asis.Text.Delimiter_Image.
308
-- Returns a null string if The_Context is uninitialized.
310
-- These values are intended for two purposes. They are suitable for
311
-- inclusion in problem reports sent to the ASIS implementor. They can be
312
-- presumed to contain information useful when debugging the implementation
313
-- itself. They are also suitable for use by the ASIS application when
314
-- printing simple application debugging messages during application
315
-- development. They are intended to be, to some worthwhile degree,
316
-- intelligible to the user.
318
end Asis.Ada_Environments;
b'\\ No newline at end of file'
added
removed
asis/asis-ada_environments.ads
