2008-05-30 Vladimir Makarov <vmakarov@redhat.com>
[official-gcc.git] / gcc / ada / sem_attr.ads
blob126c358be9f0da130f3785c5f2fa353c7b2e5b23
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT COMPILER COMPONENTS --
4 -- --
5 -- S E M _ A T T R --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 1992-2008, Free Software Foundation, Inc. --
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 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, 51 Franklin Street, Fifth Floor, --
20 -- Boston, MA 02110-1301, USA. --
21 -- --
22 -- GNAT was originally developed by the GNAT team at New York University. --
23 -- Extensive contributions were provided by Ada Core Technologies Inc. --
24 -- --
25 ------------------------------------------------------------------------------
27 -- Attribute handling is isolated in a separate package to ease the addition
28 -- of implementation defined attributes. Logically this processing belongs
29 -- in chapter 4. See Sem_Ch4 for a description of the relation of the
30 -- Analyze and Resolve routines for expression components.
32 -- This spec also documents all GNAT implementation defined pragmas
34 with Exp_Tss; use Exp_Tss;
35 with Namet; use Namet;
36 with Snames; use Snames;
37 with Types; use Types;
39 package Sem_Attr is
41 -----------------------------------------
42 -- Implementation Dependent Attributes --
43 -----------------------------------------
45 -- This section describes the implementation dependent attributes
46 -- provided in GNAT, as well as constructing an array of flags
47 -- indicating which attributes these are.
49 Attribute_Impl_Def : Attribute_Class_Array := Attribute_Class_Array'(
51 ------------------
52 -- Abort_Signal --
53 ------------------
55 Attribute_Abort_Signal => True,
56 -- Standard'Abort_Signal (Standard is the only allowed prefix) provides
57 -- the entity for the special exception used to signal task abort or
58 -- asynchronous transfer of control. Normally this attribute should only
59 -- be used in the tasking runtime (it is highly peculiar, and completely
60 -- outside the normal semantics of Ada, for a user program to intercept
61 -- the abort exception).
63 ------------------
64 -- Address_Size --
65 ------------------
67 Attribute_Address_Size => True,
68 -- Standard'Address_Size (Standard is the only allowed prefix) is
69 -- a static constant giving the number of bits in an Address. It
70 -- is used primarily for constructing the definition of Memory_Size
71 -- in package Standard, but may be freely used in user programs.
72 -- This is a static attribute.
74 ---------------
75 -- Asm_Input --
76 ---------------
78 Attribute_Asm_Input => True,
79 -- Used only in conjunction with the Asm subprograms in package
80 -- Machine_Code to construct machine instructions. See documentation
81 -- in package Machine_Code in file s-maccod.ads.
83 ----------------
84 -- Asm_Output --
85 ----------------
87 Attribute_Asm_Output => True,
88 -- Used only in conjunction with the Asm subprograms in package
89 -- Machine_Code to construct machine instructions. See documentation
90 -- in package Machine_Code in file s-maccod.ads.
92 ---------------
93 -- AST_Entry --
94 ---------------
96 Attribute_AST_Entry => True,
97 -- E'Ast_Entry, where E is a task entry, yields a value of the
98 -- predefined type System.DEC.AST_Handler, that enables the given
99 -- entry to be called when an AST occurs. If the name to which the
100 -- attribute applies has not been specified with the pragma AST_Entry,
101 -- the attribute returns the value No_Ast_Handler, and no AST occurs.
102 -- If the entry is for a task that is not callable (T'Callable False),
103 -- the exception program error is raised. If an AST occurs for an
104 -- entry of a task that is terminated, the program is erroneous.
106 -- The attribute AST_Entry is supported only in OpenVMS versions
107 -- of GNAT. It will be rejected as illegal in other GNAT versions.
109 ---------
110 -- Bit --
111 ---------
113 Attribute_Bit => True,
114 -- Obj'Bit, where Obj is any object, yields the bit offset within the
115 -- storage unit (byte) that contains the first bit of storage allocated
116 -- for the object. The attribute value is of type Universal_Integer,
117 -- and is always a non-negative number not exceeding the value of
118 -- System.Storage_Unit.
120 -- For an object that is a variable or a constant allocated in a
121 -- register, the value is zero. (The use of this attribute does not
122 -- force the allocation of a variable to memory).
124 -- For an object that is a formal parameter, this attribute applies to
125 -- either the matching actual parameter or to a copy of the matching
126 -- actual parameter.
128 -- For an access object the value is zero. Note that Obj.all'Bit is
129 -- subject to an Access_Check for the designated object. Similarly
130 -- for a record component X.C'Bit is subject to a discriminant check
131 -- and X(I).Bit and X(I1..I2)'Bit are subject to index checks.
133 -- This attribute is designed to be compatible with the DEC Ada
134 -- definition and implementation of the Bit attribute.
136 ------------------
137 -- Code_Address --
138 ------------------
140 Attribute_Code_Address => True,
141 -- The reference subp'Code_Address, where subp is a subprogram entity,
142 -- gives the address of the first generated instruction for the sub-
143 -- program. This is often, but not always the same as the 'Address
144 -- value, which is the address to be used in a call. The differences
145 -- occur in the case of a nested procedure (where Address yields the
146 -- address of the trampoline code used to load the static link), and on
147 -- some systems which use procedure descriptors (in which case Address
148 -- yields the address of the descriptor).
150 -----------------------
151 -- Default_Bit_Order --
152 -----------------------
154 Attribute_Default_Bit_Order => True,
155 -- Standard'Default_Bit_Order (Standard is the only permissible prefix),
156 -- provides the value System.Default_Bit_Order as a Pos value (0 for
157 -- High_Order_First, 1 for Low_Order_First). This is used to construct
158 -- the definition of Default_Bit_Order in package System. This is a
159 -- static attribute.
161 ---------------
162 -- Elab_Body --
163 ---------------
165 Attribute_Elab_Body => True,
166 -- This attribute can only be applied to a program unit name. It returns
167 -- the entity for the corresponding elaboration procedure for elabor-
168 -- ating the body of the referenced unit. This is used in the main
169 -- generated elaboration procedure by the binder, and is not normally
170 -- used in any other context, but there may be specialized situations in
171 -- which it is useful to be able to call this elaboration procedure from
172 -- Ada code, e.g. if it is necessary to do selective reelaboration to
173 -- fix some error.
175 ---------------
176 -- Elab_Spec --
177 ---------------
179 Attribute_Elab_Spec => True,
180 -- This attribute can only be applied to a program unit name. It
181 -- returns the entity for the corresponding elaboration procedure
182 -- for elaborating the spec of the referenced unit. This is used
183 -- in the main generated elaboration procedure by the binder, and
184 -- is not normally used in any other context, but there may be
185 -- specialized situations in which it is useful to be able to
186 -- call this elaboration procedure from Ada code, e.g. if it
187 -- is necessary to do selective reelaboration to fix some error.
189 ----------------
190 -- Elaborated --
191 ----------------
193 Attribute_Elaborated => True,
194 -- Lunit'Elaborated, where Lunit is a library unit, yields a boolean
195 -- value indicating whether or not the body of the designated library
196 -- unit has been elaborated yet.
198 --------------
199 -- Enum_Rep --
200 --------------
202 Attribute_Enum_Rep => True,
203 -- For every enumeration subtype S, S'Enum_Rep denotes a function
204 -- with the following specification:
206 -- function S'Enum_Rep (Arg : S'Base) return universal_integer;
208 -- The function returns the representation value for the given
209 -- enumeration value. This will be equal to the 'Pos value in the
210 -- absence of an enumeration representation clause. This is a static
211 -- attribute (i.e. the result is static if the argument is static).
213 --------------
214 -- Enum_Val --
215 --------------
217 Attribute_Enum_Val => True,
218 -- For every enumeration subtype S, S'Enum_Val denotes a function
219 -- with the following specification:
221 -- function S'Enum_Val (Arg : universal_integer) return S'Base;
223 -- This function performs the inverse transformation to Enum_Rep. Given
224 -- a representation value for the type, it returns the corresponding
225 -- enumeration value. Constraint_Error is raised if no value of the
226 -- enumeration type corresponds to the given integer value.
228 -----------------
229 -- Fixed_Value --
230 -----------------
232 Attribute_Fixed_Value => True,
233 -- For every fixed-point type S, S'Fixed_Value denotes a function
234 -- with the following specification:
236 -- function S'Fixed_Value (Arg : universal_integer) return S;
238 -- The value returned is the fixed-point value V such that
240 -- V = Arg * S'Small
242 -- The effect is thus equivalent to first converting the argument to
243 -- the integer type used to represent S, and then doing an unchecked
244 -- conversion to the fixed-point type. This attribute is primarily
245 -- intended for use in implementation of the input-output functions for
246 -- fixed-point values.
248 -----------------------
249 -- Has_Discriminants --
250 -----------------------
252 Attribute_Has_Discriminants => True,
253 -- Gtyp'Has_Discriminants, where Gtyp is a generic formal type, yields
254 -- a Boolean value indicating whether or not the actual instantiation
255 -- type has discriminants.
257 ---------
258 -- Img --
259 ---------
261 Attribute_Img => True,
262 -- The 'Img function is defined for any prefix, P, that denotes an
263 -- object of scalar type T. P'Img is equivalent to T'Image (P). This
264 -- is convenient for debugging. For example:
266 -- Put_Line ("X = " & X'Img);
268 -- has the same meaning as the more verbose:
270 -- Put_Line ("X = " & Temperature_Type'Image (X));
272 -- where Temperature_Type is the subtype of the object X.
274 -------------------
275 -- Integer_Value --
276 -------------------
278 Attribute_Integer_Value => True,
279 -- For every integer type S, S'Integer_Value denotes a function
280 -- with the following specification:
282 -- function S'Integer_Value (Arg : universal_fixed) return S;
284 -- The value returned is the integer value V, such that
286 -- Arg = V * fixed-type'Small
288 -- The effect is thus equivalent to first doing an unchecked convert
289 -- from the fixed-point type to its corresponding implementation type,
290 -- and then converting the result to the target integer type. This
291 -- attribute is primarily intended for use in implementation of the
292 -- standard input-output functions for fixed-point values.
294 Attribute_Invalid_Value => True,
295 -- For every scalar type, S'Invalid_Value designates an undefined value
296 -- of the type. If possible this value is an invalid value, and in fact
297 -- is identical to the value that would be set if Initialize_Scalars
298 -- mode were in effect (including the behavior of its value on
299 -- environment variables or binder switches). The intended use is
300 -- to set a value where initialization is required (e.g. as a result of
301 -- the coding standards in use), but logically no initialization is
302 -- needed, and the value should never be accessed.
304 ------------------
305 -- Machine_Size --
306 ------------------
308 Attribute_Machine_Size => True,
309 -- This attribute is identical to the Object_Size attribute. It is
310 -- provided for compatibility with the DEC attribute of this name.
312 -----------------------
313 -- Maximum_Alignment --
314 -----------------------
316 Attribute_Maximum_Alignment => True,
317 -- Standard'Maximum_Alignment (Standard is the only permissible prefix)
318 -- provides the maximum useful alignment value for the target. This
319 -- is a static value that can be used to specify the alignment for an
320 -- object, guaranteeing that it is properly aligned in all cases. The
321 -- time this is useful is when an external object is imported and its
322 -- alignment requirements are unknown. This is a static attribute.
324 --------------------
325 -- Mechanism_Code --
326 --------------------
328 Attribute_Mechanism_Code => True,
329 -- function'Mechanism_Code yields an integer code for the mechanism
330 -- used for the result of function, and subprogram'Mechanism_Code (n)
331 -- yields the mechanism used for formal parameter number n (a static
332 -- integer value, 1 = first parameter). The code returned is:
334 -- 1 = by copy (value)
335 -- 2 = by reference
336 -- 3 = by descriptor (default descriptor type)
337 -- 4 = by descriptor (UBS unaligned bit string)
338 -- 5 = by descriptor (UBSB aligned bit string with arbitrary bounds)
339 -- 6 = by descriptor (UBA unaligned bit array)
340 -- 7 = by descriptor (S string, also scalar access type parameter)
341 -- 8 = by descriptor (SB string with arbitrary bounds)
342 -- 9 = by descriptor (A contiguous array)
343 -- 10 = by descriptor (NCA non-contiguous array)
345 --------------------
346 -- Null_Parameter --
347 --------------------
349 Attribute_Null_Parameter => True,
350 -- A reference T'Null_Parameter denotes an (imaginary) object of type or
351 -- subtype T allocated at (machine) address zero. The attribute is
352 -- allowed only as the default expression of a formal parameter, or as
353 -- an actual expression of a subprogram call. In either case, the
354 -- subprogram must be imported.
356 -- The identity of the object is represented by the address zero in the
357 -- argument list, independent of the passing mechanism (explicit or
358 -- default).
360 -- The reason that this capability is needed is that for a record or
361 -- other composite object passed by reference, there is no other way of
362 -- specifying that a zero address should be passed.
364 -----------------
365 -- Object_Size --
366 -----------------
368 Attribute_Object_Size => True,
369 -- Type'Object_Size is the same as Type'Size for all types except
370 -- fixed-point types and discrete types. For fixed-point types and
371 -- discrete types, this attribute gives the size used for default
372 -- allocation of objects and components of the size. See section in
373 -- Einfo ("Handling of type'Size values") for further details.
375 -------------------------
376 -- Passed_By_Reference --
377 -------------------------
379 Attribute_Passed_By_Reference => True,
380 -- T'Passed_By_Reference for any subtype T returns a boolean value that
381 -- is true if the type is normally passed by reference and false if the
382 -- type is normally passed by copy in calls. For scalar types, the
383 -- result is always False and is static. For non-scalar types, the
384 -- result is non-static (since it is computed by Gigi).
386 ------------------
387 -- Range_Length --
388 ------------------
390 Attribute_Range_Length => True,
391 -- T'Range_Length for any discrete type T yields the number of values
392 -- represented by the subtype (zero for a null range). The result is
393 -- static for static subtypes. Note that Range_Length applied to the
394 -- index subtype of a one dimensional array always gives the same result
395 -- as Range applied to the array itself. The result is of type universal
396 -- integer.
398 ------------------
399 -- Storage_Unit --
400 ------------------
402 Attribute_Storage_Unit => True,
403 -- Standard'Storage_Unit (Standard is the only permissible prefix)
404 -- provides the value System.Storage_Unit, and is intended primarily
405 -- for constructing this definition in package System (see note above
406 -- in Default_Bit_Order description). The is a static attribute.
408 ---------------
409 -- Stub_Type --
410 ---------------
412 Attribute_Stub_Type => True,
413 -- The GNAT implementation of remote access-to-classwide types is
414 -- organised as described in AARM E.4(20.t): a value of an RACW type
415 -- (designating a remote object) is represented as a normal access
416 -- value, pointing to a "stub" object which in turn contains the
417 -- necessary information to contact the designated remote object. A
418 -- call on any dispatching operation of such a stub object does the
419 -- remote call, if necessary, using the information in the stub object
420 -- to locate the target partition, etc.
422 -- For a prefix T that denotes a remote access-to-classwide type,
423 -- T'Stub_Type denotes the type of the corresponding stub objects.
425 -- By construction, the layout of T'Stub_Type is identical to that of
426 -- System.Partition_Interface.RACW_Stub_Type (see implementation notes
427 -- in body of Exp_Dist).
429 -----------------
430 -- Target_Name --
431 -----------------
433 Attribute_Target_Name => True,
434 -- Standard'Target_Name yields the string identifying the target for the
435 -- compilation, taken from Sdefault.Target_Name.
437 ----------------
438 -- To_Address --
439 ----------------
441 Attribute_To_Address => True,
442 -- System'To_Address (Address is the only permissible prefix) is a
443 -- function that takes any integer value, and converts it into an
444 -- address value. The semantics is to first convert the integer value to
445 -- type Integer_Address according to normal conversion rules, and then
446 -- to convert this to an address using the same semantics as the
447 -- System.Storage_Elements.To_Address function. The important difference
448 -- is that this is a static attribute so it can be used in
449 -- initializations in preelaborate packages.
451 ----------------
452 -- Type_Class --
453 ----------------
455 Attribute_Type_Class => True,
456 -- T'Type_Class for any type or subtype T yields the value of the type
457 -- class for the full type of T. If T is a generic formal type, then the
458 -- value is the value for the corresponding actual subtype. The value of
459 -- this attribute is of type System.Aux_DEC.Type_Class, which has the
460 -- following definition:
462 -- type Type_Class is
463 -- (Type_Class_Enumeration,
464 -- Type_Class_Integer,
465 -- Type_Class_Fixed_Point,
466 -- Type_Class_Floating_Point,
467 -- Type_Class_Array,
468 -- Type_Class_Record,
469 -- Type_Class_Access,
470 -- Type_Class_Task,
471 -- Type_Class_Address);
473 -- Protected types yield the value Type_Class_Task, which thus applies
474 -- to all concurrent types. This attribute is designed to be compatible
475 -- with the DEC Ada attribute of the same name.
477 -- Note: if pragma Extend_System is used to merge the definitions of
478 -- Aux_DEC into System, then the type Type_Class can be referenced
479 -- as an entity within System, as can its enumeration literals.
481 -----------------
482 -- UET_Address --
483 -----------------
485 Attribute_UET_Address => True,
486 -- Unit'UET_Address, where Unit is a program unit, yields the address
487 -- of the unit exception table for the specified unit. This is only
488 -- used in the internal implementation of exception handling. See the
489 -- implementation of unit Ada.Exceptions for details on its use.
491 ------------------------------
492 -- Universal_Literal_String --
493 ------------------------------
495 Attribute_Universal_Literal_String => True,
496 -- The prefix of 'Universal_Literal_String must be a named number. The
497 -- static result is the string consisting of the characters of the
498 -- number as defined in the original source. This allows the user
499 -- program to access the actual text of named numbers without
500 -- intermediate conversions and without the need to enclose the strings
501 -- in quotes (which would preclude their use as numbers). This is used
502 -- internally for the construction of values of the floating-point
503 -- attributes from the file ttypef.ads, but may also be used by user
504 -- programs.
506 -------------------------
507 -- Unrestricted_Access --
508 -------------------------
510 Attribute_Unrestricted_Access => True,
511 -- The Unrestricted_Access attribute is similar to Access except that
512 -- all accessibility and aliased view checks are omitted. This is very
513 -- much a user-beware attribute. Basically its status is very similar
514 -- to Address, for which it is a desirable replacement where the value
515 -- desired is an access type. In other words, its effect is identical
516 -- to first taking 'Address and then doing an unchecked conversion to
517 -- a desired access type. Note that in GNAT, but not necessarily in
518 -- other implementations, the use of static chains for inner level
519 -- subprograms means that Unrestricted_Access applied to a subprogram
520 -- yields a value that can be called as long as the subprogram is in
521 -- scope (normal Ada 95 accessibility rules restrict this usage).
523 ---------------
524 -- VADS_Size --
525 ---------------
527 Attribute_VADS_Size => True,
528 -- Typ'VADS_Size yields the Size value typically yielded by some Ada 83
529 -- compilers. The differences between VADS_Size and Size is that for
530 -- scalar types for which no Size has been specified, VADS_Size yields
531 -- the Object_Size rather than the Value_Size. For example, while
532 -- Natural'Size is typically 31, the value of Natural'VADS_Size is 32.
533 -- For all other types, Size and VADS_Size yield the same value.
535 ----------------
536 -- Value_Size --
537 ----------------
539 Attribute_Value_Size => True,
540 -- Type'Value_Size is the number of bits required to represent value of
541 -- the given subtype. It is the same as Type'Size, but, unlike Size, may
542 -- be set for non-first subtypes. See section in Einfo ("Handling of
543 -- type'Size values") for further details.
545 ---------------
546 -- Word_Size --
547 ---------------
549 Attribute_Word_Size => True,
550 -- Standard'Word_Size (Standard is the only permissible prefix)
551 -- provides the value System.Word_Size, and is intended primarily
552 -- for constructing this definition in package System (see note above
553 -- in Default_Bit_Order description). This is a static attribute.
555 others => False);
557 -----------------
558 -- Subprograms --
559 -----------------
561 procedure Analyze_Attribute (N : Node_Id);
562 -- Performs bottom up semantic analysis of an attribute. Note that the
563 -- parser has already checked that type returning attributes appear only
564 -- in appropriate contexts (i.e. in subtype marks, or as prefixes for
565 -- other attributes).
567 function Name_Implies_Lvalue_Prefix (Nam : Name_Id) return Boolean;
568 -- Determine whether the name of an attribute reference categorizes its
569 -- prefix as an lvalue. The following attributes fall under this bracket
570 -- by directly or indirectly modifying their prefixes.
571 -- Access
572 -- Address
573 -- Input
574 -- Read
575 -- Unchecked_Access
576 -- Unrestricted_Access
578 procedure Resolve_Attribute (N : Node_Id; Typ : Entity_Id);
579 -- Performs type resolution of attribute. If the attribute yields a
580 -- universal value, mark its type as that of the context. On the other
581 -- hand, if the context itself is universal (as in T'Val (T'Pos (X)), mark
582 -- the type as being the largest type of that class that can be used at
583 -- run-time. This is correct since either the value gets folded (in which
584 -- case it doesn't matter what type of the class we give if, since the
585 -- folding uses universal arithmetic anyway) or it doesn't get folded (in
586 -- which case it is going to be dealt with at runtime, and the largest type
587 -- is right).
589 function Stream_Attribute_Available
590 (Typ : Entity_Id;
591 Nam : TSS_Name_Type;
592 Partial_View : Entity_Id := Empty) return Boolean;
593 -- For a limited type Typ, return True iff the given attribute is
594 -- available. For Ada 05, availability is defined by 13.13.2(36/1). For Ada
595 -- 95, an attribute is considered to be available if it has been specified
596 -- using an attribute definition clause for the type, or for its full view,
597 -- or for an ancestor of either. Parameter Partial_View is used only
598 -- internally, when checking for an attribute definition clause that is not
599 -- visible (Ada 95 only).
601 end Sem_Attr;