gcc/ada/sem_attr.ads

   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-2003, 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,  59 Temple Place - Suite 330,  Boston, --
  20 -- MA 02111-1307, 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 ------------------------------------------------------------------------------
  26
  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.
  31
  32 --  This spec also documents all GNAT implementation defined pragmas
  33
  34 with Snames; use Snames;
  35 with Types;  use Types;
  36
  37 package Sem_Attr is
  38
  39    type Attribute_Class_Array is array (Attribute_Id) of Boolean;
  40    --  Type used to build attribute classification flag arrays
  41
  42    -----------------------------------------
  43    -- Implementation Dependent Attributes --
  44    -----------------------------------------
  45
  46    --  This section describes the implementation dependent attributes
  47    --  provided in GNAT, as well as constructing an array of flags
  48    --  indicating which attributes these are.
  49
  50    Attribute_Impl_Def : Attribute_Class_Array := Attribute_Class_Array'(
  51
  52       ------------------
  53       -- Abort_Signal --
  54       ------------------
  55
  56       Attribute_Abort_Signal => True,
  57       --
  58       --  Standard'Abort_Signal (Standard is the only allowed prefix)
  59       --  provides the entity for the special exception used to signal
  60       --  task abort or asynchronous transfer of control. Normally this
  61       --  attribute should only be used in the tasking runtime (it is
  62       --  highly peculiar, and completely outside the normal semantics
  63       --  of Ada, for a user program to intercept the abort exception).
  64
  65       ------------------
  66       -- Address_Size --
  67       ------------------
  68
  69       Attribute_Address_Size => True,
  70       --
  71       --  Standard'Address_Size (Standard is the only allowed prefix) is
  72       --  a static constant giving the number of bits in an Address. It
  73       --  is used primarily for constructing the definition of Memory_Size
  74       --  in package Standard, but may be freely used in user programs.
  75       --  This is a static attribute.
  76
  77       ---------------
  78       -- Asm_Input --
  79       ---------------
  80
  81       Attribute_Asm_Input => True,
  82       --
  83       --  Used only in conjunction with the Asm and Asm_Volatile subprograms
  84       --  in package Machine_Code to construct machine instructions. See
  85       --  documentation in package Machine_Code in file s-maccod.ads.
  86
  87       ----------------
  88       -- Asm_Output --
  89       ----------------
  90
  91       Attribute_Asm_Output => True,
  92       --
  93       --  Used only in conjunction with the Asm and Asm_Volatile subprograms
  94       --  in package Machine_Code to construct machine instructions. See
  95       --  documentation in package Machine_Code in file s-maccod.ads.
  96
  97       ---------------
  98       -- AST_Entry --
  99       ---------------
 100
 101       Attribute_AST_Entry => True,
 102       --
 103       --  E'Ast_Entry, where E is a task entry, yields a value of the
 104       --  predefined type System.DEC.AST_Handler, that enables the given
 105       --  entry to be called when an AST occurs. If the name to which the
 106       --  attribute applies has not been specified with the pragma AST_Entry,
 107       --  the attribute returns the value No_Ast_Handler, and no AST occurs.
 108       --  If the entry is for a task that is not callable (T'Callable False),
 109       --  the exception program error is raised. If an AST occurs for an
 110       --  entry of a task that is terminated, the program is erroneous.
 111       --
 112       --  The attribute AST_Entry is supported only in OpenVMS versions
 113       --  of GNAT. It will be rejected as illegal in other GNAT versions.
 114
 115       ---------
 116       -- Bit --
 117       ---------
 118
 119       Attribute_Bit => True,
 120       --
 121       --  Obj'Bit, where Obj is any object, yields the bit offset within
 122       --  the storage unit (byte) that contains the first bit of storage
 123       --  allocated for the object. The value of this attribute is of the
 124       --  type Universal_Integer, and is always a non-negative number not
 125       --  exceeding the value of System.Storage_Unit.
 126       --
 127       --  For an object that is a variable or a constant allocated in a
 128       --  register, the value is zero. (The use of this attribute does not
 129       --  force the allocation of a variable to memory).
 130       --
 131       --  For an object that is a formal parameter, this attribute applies
 132       --  to either the matching actual parameter or to a copy of the
 133       --  matching actual parameter.
 134       --
 135       --  For an access object the value is zero. Note that Obj.all'Bit is
 136       --  subject to an Access_Check for the designated object. Similarly
 137       --  for a record component X.C'Bit is subject to a discriminant check
 138       --  and X(I).Bit and X(I1..I2)'Bit are subject to index checks.
 139       --
 140       --  This attribute is designed to be compatible with the DEC Ada
 141       --  definition and implementation of the Bit attribute.
 142
 143       ------------------
 144       -- Code_Address --
 145       ------------------
 146
 147       Attribute_Code_Address => True,
 148       --
 149       --  subp'Code_Address, where subp is a subprogram entity, gives the
 150       --  address of the first generated instruction for a subprogram. This
 151       --  is often, but not always the same as the 'Address value, which is
 152       --  the address to be used in a call. The differences occur in the case
 153       --  of a nested procedure (where Address yields the address of the
 154       --  trampoline code used to load the static link), and on some systems
 155       --  which use procedure descriptors (in which case Address yields the
 156       --  address of the descriptor).
 157
 158       -----------------------
 159       -- Default_Bit_Order --
 160       -----------------------
 161
 162       Attribute_Default_Bit_Order => True,
 163       --
 164       --  Standard'Default_Bit_Order (Standard is the only permissible prefix),
 165       --  provides the value System.Default_Bit_Order as a Pos value (0 for
 166       --  High_Order_First, 1 for Low_Order_First). This is used to construct
 167       --  the definition of Default_Bit_Order in package System. This is a
 168       --  static attribute.
 169
 170       ---------------
 171       -- Elab_Body --
 172       ---------------
 173
 174       Attribute_Elab_Body => True,
 175       --
 176       --  This attribute can only be applied to a program unit name. It
 177       --  returns the entity for the corresponding elaboration procedure
 178       --  for elaborating the body of the referenced unit. This is used
 179       --  in the main generated elaboration procedure by the binder, and
 180       --  is not normally used in any other context, but there may be
 181       --  specialized situations in which it is useful to be able to
 182       --  call this elaboration procedure from Ada code, e.g. if it
 183       --  is necessary to do selective reelaboration to fix some error.
 184
 185       ---------------
 186       -- Elab_Spec --
 187       ---------------
 188
 189       Attribute_Elab_Spec => True,
 190       --
 191       --  This attribute can only be applied to a program unit name. It
 192       --  returns the entity for the corresponding elaboration procedure
 193       --  for elaborating the spec of the referenced unit. This is used
 194       --  in the main generated elaboration procedure by the binder, and
 195       --  is not normally used in any other context, but there may be
 196       --  specialized situations in which it is useful to be able to
 197       --  call this elaboration procedure from Ada code, e.g. if it
 198       --  is necessary to do selective reelaboration to fix some error.
 199
 200       ----------------
 201       -- Elaborated --
 202       ----------------
 203
 204       Attribute_Elaborated => True,
 205       --
 206       --  Lunit'Elaborated, where Lunit is a library unit, yields a boolean
 207       --  value indicating whether or not the body of the designated library
 208       --  unit has been elaborated yet.
 209
 210       --------------
 211       -- Enum_Rep --
 212       --------------
 213
 214       Attribute_Enum_Rep => True,
 215       --
 216       --  For every enumeration subtype S, S'Enum_Rep denotes a function
 217       --  with the following specification:
 218       --
 219       --    function S'Enum_Rep (Arg : S'Base) return universal_integer;
 220       --
 221       --  The function returns the representation value for the given
 222       --  enumeration value. This will be equal to the 'Pos value in the
 223       --  absence of an enumeration representation clause. This is a static
 224       --  attribute (i.e. the result is static if the argument is static).
 225
 226       -----------------
 227       -- Fixed_Value --
 228       -----------------
 229
 230       Attribute_Fixed_Value => True,
 231       --
 232       --  For every fixed-point type S, S'Fixed_Value denotes a function
 233       --  with the following specification:
 234       --
 235       --    function S'Fixed_Value (Arg : universal_integer) return S;
 236       --
 237       --  The value returned is the fixed-point value V such that
 238       --
 239       --    V = Arg * S'Small
 240       --
 241       --  The effect is thus equivalent to first converting the argument
 242       --  to the integer type used to represent S, and then doing an
 243       --  unchecked conversion to the fixed-point type. This attribute is
 244       --  primarily intended for use in implementation of the input-output
 245       --  functions for fixed-point values.
 246
 247       -----------------------
 248       -- Has_Discriminants --
 249       -----------------------
 250
 251       Attribute_Has_Discriminants => True,
 252       --
 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.
 256
 257       ---------
 258       -- Img --
 259       ---------
 260
 261       Attribute_Img => True,
 262       --
 263       --  The 'Img function is defined for any prefix, P, that denotes an
 264       --  object of scalar type T. P'Img is equivalent to T'Image (P). This
 265       --  is convenient for debugging. For example:
 266       --
 267       --     Put_Line ("X = " & X'Img);
 268       --
 269       --  has the same meaning as the more verbose:
 270       --
 271       --     Put_Line ("X = " & Temperature_Type'Image (X));
 272       --
 273       --  where Temperature_Type is the subtype of the object X.
 274
 275       -------------------
 276       -- Integer_Value --
 277       -------------------
 278
 279       Attribute_Integer_Value => True,
 280       --
 281       --  For every integer type S, S'Integer_Value denotes a function
 282       --  with the following specification:
 283       --
 284       --    function S'Integer_Value (Arg : universal_fixed) return S;
 285       --
 286       --  The value returned is the integer value V, such that
 287       --
 288       --    Arg = V * fixed-type'Small
 289       --
 290       --  The effect is thus equivalent to first doing an unchecked convert
 291       --  from the fixed-point type to its corresponding implementation type,
 292       --  and then converting the result to the target integer type. This
 293       --  attribute is primarily intended for use in implementation of the
 294       --  standard input-output functions for fixed-point values.
 295
 296       ------------------
 297       -- Machine_Size --
 298       ------------------
 299
 300       Attribute_Machine_Size => True,
 301       --
 302       --  This attribute is identical to the Object_Size attribute. It is
 303       --  provided for compatibility with the DEC attribute of this name.
 304
 305       -----------------------
 306       -- Maximum_Alignment --
 307       -----------------------
 308
 309       Attribute_Maximum_Alignment => True,
 310       --
 311       --  Standard'Maximum_Alignment (Standard is the only permissible prefix)
 312       --  provides the maximum useful alignment value for the target. This
 313       --  is a static value that can be used to specify the alignment for an
 314       --  object, guaranteeing that it is properly aligned in all cases. The
 315       --  time this is useful is when an external object is imported and its
 316       --  alignment requirements are unknown. This is a static attribute.
 317
 318       --------------------
 319       -- Mechanism_Code --
 320       --------------------
 321
 322       Attribute_Mechanism_Code => True,
 323       --
 324       --  function'Mechanism_Code yeilds an integer code for the mechanism
 325       --  used for the result of function, and subprogram'Mechanism_Code (n)
 326       --  yields the mechanism used for formal parameter number n (a static
 327       --  integer value, 1 = first parameter). The code returned is:
 328       --
 329       --     1 = by copy (value)
 330       --     2 = by reference
 331       --     3 = by descriptor (default descriptor type)
 332       --     4 = by descriptor (UBS  unaligned bit string)
 333       --     5 = by descriptor (UBSB aligned bit string with arbitrary bounds)
 334       --     6 = by descriptor (UBA  unaligned bit array)
 335       --     7 = by descriptor (S    string, also scalar access type parameter)
 336       --     8 = by descriptor (SB   string with arbitrary bounds)
 337       --     9 = by descriptor (A    contiguous array)
 338       --    10 = by descriptor (NCA  non-contiguous array)
 339
 340       --------------------
 341       -- Null_Parameter --
 342       --------------------
 343
 344       Attribute_Null_Parameter => True,
 345       --
 346       --  A reference T'Null_Parameter denotes an (imaginary) object of
 347       --  type or subtype T allocated at (machine) address zero. The
 348       --  attribute is allowed only as the default expression of a formal
 349       --  parameter, or as an actual expression of a subporgram call. In
 350       --  either case, the subprogram must be imported.
 351       --
 352       --  The identity of the object is represented by the address zero
 353       --  in the argument list, independent of the passing mechanism
 354       --  (explicit or default).
 355       --
 356       --  The reason that this capability is needed is that for a record
 357       --  or other composite object passed by reference, there is no other
 358       --  way of specifying that a zero address should be passed.
 359
 360       -----------------
 361       -- Object_Size --
 362       -----------------
 363
 364       Attribute_Object_Size => True,
 365       --
 366       --  Type'Object_Size is the same as Type'Size for all types except
 367       --  fixed-point types and discrete types. For fixed-point types and
 368       --  discrete types, this attribute gives the size used for default
 369       --  allocation of objects and components of the size. See section
 370       --  in Einfo ("Handling of type'Size values") for further details.
 371
 372       -------------------------
 373       -- Passed_By_Reference --
 374       -------------------------
 375
 376       Attribute_Passed_By_Reference => True,
 377       --
 378       --  T'Passed_By_Reference for any subtype T returns a boolean value
 379       --  that is true if the type is normally passed by reference and
 380       --  false if the type is normally passed by copy in calls. For scalar
 381       --  types, the result is always False and is static. For non-scalar
 382       --  types, the result is non-static (since it is computed by Gigi).
 383
 384       ------------------
 385       -- Range_Length --
 386       ------------------
 387
 388       Attribute_Range_Length => True,
 389       --
 390       --  T'Range_Length for any discrete type T yields the number of
 391       --  values represented by the subtype (zero for a null range). The
 392       --  result is static for static subtypes. Note that Range_Length
 393       --  applied to the index subtype of a one dimensional array always
 394       --  gives the same result as Range applied to the array itself.
 395       --  The result is of type universal integer.
 396
 397       ------------------
 398       -- Storage_Unit --
 399       ------------------
 400
 401       Attribute_Storage_Unit => True,
 402       --
 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.
 407
 408       -----------------
 409       -- Target_Name --
 410       -----------------
 411
 412       Attribute_Target_Name => True,
 413       --
 414       --  Standard'Target_Name yields the string identifying the target
 415       --  for the compilation, taken from Sdefault.Target_Name.
 416
 417       ----------------
 418       -- To_Address --
 419       ----------------
 420
 421       Attribute_To_Address => True,
 422       --
 423       --  System'To_Address (Address is the only permissible prefix)
 424       --  is a function that takes any integer value, and converts it into
 425       --  an address value. The semantics is to first convert the integer
 426       --  value to type Integer_Address according to normal conversion
 427       --  rules, and then to convert this to an address using the same
 428       --  semantics as the System.Storage_Elements.To_Address function.
 429       --  The important difference is that this is a static attribute
 430       --  so it can be used in initializations in preealborate packages.
 431
 432       ----------------
 433       -- Type_Class --
 434       ----------------
 435
 436       Attribute_Type_Class => True,
 437       --
 438       --  T'Type_Class for any type or subtype T yields the value of the
 439       --  type class for the full type of T. If T is a generic formal type,
 440       --  then the value is the value for the corresponding actual subtype.
 441       --  The value of this attribute is of type System.Aux_DEC.Type_Class,
 442       --  which has the following definition:
 443       --
 444       --    type Type_Class is
 445       --      (Type_Class_Enumeration,
 446       --       Type_Class_Integer,
 447       --       Type_Class_Fixed_Point,
 448       --       Type_Class_Floating_Point,
 449       --       Type_Class_Array,
 450       --       Type_Class_Record,
 451       --       Type_Class_Access,
 452       --       Type_Class_Task,
 453       --       Type_Class_Address);
 454       --
 455       --  Protected types yield the value Type_Class_Task, which thus
 456       --  applies to all concurrent types. This attribute is designed to
 457       --  be compatible with the DEC Ada attribute of the same name.
 458       --
 459       --  Note: if pragma Extend_System is used to merge the definitions of
 460       --  Aux_DEC into System, then the type Type_Class can be referenced
 461       --  as an entity within System, as can its enumeration literals.
 462
 463       -----------------
 464       -- UET_Address --
 465       -----------------
 466
 467       Attribute_UET_Address => True,
 468       --
 469       --  Unit'UET_Address, where Unit is a program unit, yields the address
 470       --  of the unit exception table for the specified unit. This is only
 471       --  used in the internal implementation of exception handling. See the
 472       --  implementation of unit Ada.Exceptions for details on its use.
 473
 474       ------------------------------
 475       -- Universal_Literal_String --
 476       ------------------------------
 477
 478       Attribute_Universal_Literal_String => True,
 479       --
 480       --  The prefix of 'Universal_Literal_String must be a named number.
 481       --  The static result is the string consisting of the characters of
 482       --  the number as defined in the original source. This allows the
 483       --  user program to access the actual text of named numbers without
 484       --  intermediate conversions and without the need to enclose the
 485       --  strings in quotes (which would preclude their use as numbers).
 486       --  This is used internally for the construction of values of the
 487       --  floating-point attributes from the file ttypef.ads, but may
 488       --  also be used by user programs.
 489
 490       -------------------------
 491       -- Unrestricted_Access --
 492       -------------------------
 493
 494       Attribute_Unrestricted_Access => True,
 495       --
 496       --  The Unrestricted_Access attribute is similar to Access except that
 497       --  all accessibility and aliased view checks are omitted. This is very
 498       --  much a user-beware attribute. Basically its status is very similar
 499       --  to Address, for which it is a desirable replacement where the value
 500       --  desired is an access type. In other words, its effect is identical
 501       --  to first taking 'Address and then doing an unchecked conversion to
 502       --  a desired access type. Note that in GNAT, but not necessarily in
 503       --  other implementations, the use of static chains for inner level
 504       --  subprograms means that Unrestricted_Access applied to a subprogram
 505       --  yields a value that can be called as long as the subprogram is in
 506       --  scope (normal Ada 95 accessibility rules restrict this usage).
 507
 508       ---------------
 509       -- VADS_Size --
 510       ---------------
 511
 512       Attribute_VADS_Size => True,
 513       --
 514       --  Typ'VADS_Size yields the Size value typically yielded by some
 515       --  Ada 83 compilers. The differences between VADS_Size and Size
 516       --  is that for scalar types for which no Size has been specified,
 517       --  VADS_Size yields the Object_Size rather than the Value_Size.
 518       --  For example, while Natural'Size is typically 31, the value of
 519       --  Natural'VADS_Size is 32. For all other types, Size and VADS_Size
 520       --  yield the same value.
 521
 522       ----------------
 523       -- Value_Size --
 524       ----------------
 525
 526       Attribute_Value_Size => True,
 527       --
 528       --  Type'Value_Size is the number of bits required to represent a
 529       --  value of the given subtype. It is the same as Type'Size, but,
 530       --  unlike Size, may be set for non-first subtypes. See section
 531       --  in Einfo ("Handling of type'Size values") for further details.
 532
 533       ---------------
 534       -- Word_Size --
 535       ---------------
 536
 537       Attribute_Word_Size => True,
 538       --
 539       --  Standard'Word_Size (Standard is the only permissible prefix)
 540       --  provides the value System.Word_Size, and is intended primarily
 541       --  for constructing this definition in package System (see note above
 542       --  in Default_Bit_Order description). This is a static attribute.
 543
 544       others => False);
 545
 546    -----------------
 547    -- Subprograms --
 548    -----------------
 549
 550    procedure Analyze_Attribute (N : Node_Id);
 551    --  Performs bottom up semantic analysis of an attribute. Note that the
 552    --  parser has already checked that type returning attributes appear only
 553    --  in appropriate contexts (i.e. in subtype marks, or as prefixes for
 554    --  other attributes).
 555
 556    procedure Resolve_Attribute (N : Node_Id; Typ : Entity_Id);
 557    --  Performs type resolution of attribute. If the attribute yields
 558    --  a universal value, mark its type as that of the context. On
 559    --  the other hand, if the context itself is universal (as in
 560    --  T'Val (T'Pos (X)), mark the type as being the largest type of
 561    --  that class that can be used at run-time. This is correct since
 562    --  either the value gets folded (in which case it doesn't matter
 563    --  what type of the class we give if, since the folding uses universal
 564    --  arithmetic anyway) or it doesn't get folded (in which case it is
 565    --  going to be dealt with at runtime, and the largest type is right).
 566
 567 end Sem_Attr;