gcc/ada/aspects.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                              A S P E C T S                               --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --         Copyright (C) 2010-2011, 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 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.                                     --
  17 --                                                                          --
  18 -- As a special exception under Section 7 of GPL version 3, you are granted --
  19 -- additional permissions described in the GCC Runtime Library Exception,   --
  20 -- version 3.1, as published by the Free Software Foundation.               --
  21 --                                                                          --
  22 -- You should have received a copy of the GNU General Public License and    --
  23 -- a copy of the GCC Runtime Library Exception along with this program;     --
  24 -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
  25 -- <http://www.gnu.org/licenses/>.                                          --
  26 --                                                                          --
  27 -- GNAT was originally developed  by the GNAT team at  New York University. --
  28 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  29 --                                                                          --
  30 ------------------------------------------------------------------------------
  31
  32 --  This package defines the aspects that are recognized by GNAT in aspect
  33 --  specifications. It also contains the subprograms for storing/retrieving
  34 --  aspect specifications from the tree. The semantic processing for aspect
  35 --  specifications is found in Sem_Ch13.Analyze_Aspect_Specifications.
  36
  37 with Namet;  use Namet;
  38 with Snames; use Snames;
  39 with Types;  use Types;
  40
  41 package Aspects is
  42
  43    --  Type defining recognized aspects
  44
  45    type Aspect_Id is
  46      (No_Aspect,                            -- Dummy entry for no aspect
  47       Aspect_Address,
  48       Aspect_Alignment,
  49       Aspect_Attach_Handler,
  50       Aspect_Bit_Order,
  51       Aspect_Component_Size,
  52       Aspect_Constant_Indexing,
  53       Aspect_CPU,
  54       Aspect_Default_Component_Value,
  55       Aspect_Default_Iterator,
  56       Aspect_Default_Value,
  57       Aspect_Dispatching_Domain,
  58       Aspect_Dynamic_Predicate,
  59       Aspect_External_Tag,
  60       Aspect_Implicit_Dereference,
  61       Aspect_Input,
  62       Aspect_Interrupt_Priority,
  63       Aspect_Invariant,
  64       Aspect_Iterator_Element,
  65       Aspect_Machine_Radix,
  66       Aspect_Object_Size,                   -- GNAT
  67       Aspect_Output,
  68       Aspect_Post,
  69       Aspect_Postcondition,
  70       Aspect_Pre,
  71       Aspect_Precondition,
  72       Aspect_Predicate,                     -- GNAT
  73       Aspect_Priority,
  74       Aspect_Read,
  75       Aspect_Size,
  76       Aspect_Small,
  77       Aspect_Static_Predicate,
  78       Aspect_Storage_Pool,
  79       Aspect_Storage_Size,
  80       Aspect_Stream_Size,
  81       Aspect_Suppress,
  82       Aspect_Test_Case,                     -- GNAT
  83       Aspect_Type_Invariant,
  84       Aspect_Unsuppress,
  85       Aspect_Value_Size,                    -- GNAT
  86       Aspect_Variable_Indexing,
  87       Aspect_Warnings,
  88       Aspect_Write,
  89
  90       --  The following aspects correspond to library unit pragmas
  91
  92       Aspect_All_Calls_Remote,
  93       Aspect_Compiler_Unit,                 -- GNAT
  94       Aspect_Elaborate_Body,
  95       Aspect_Preelaborate,
  96       Aspect_Preelaborate_05,               -- GNAT
  97       Aspect_Pure,
  98       Aspect_Pure_05,                       -- GNAT
  99       Aspect_Remote_Call_Interface,
 100       Aspect_Remote_Types,
 101       Aspect_Shared_Passive,
 102       Aspect_Universal_Data,                -- GNAT
 103
 104       --  Remaining aspects have a static boolean value that turns the aspect
 105       --  on or off. They all correspond to pragmas, but are only converted to
 106       --  the pragmas where the value is True. A value of False normally means
 107       --  that the aspect is ignored, except in the case of derived types where
 108       --  the aspect value is inherited from the parent, in which case, we do
 109       --  not allow False if we inherit a True value from the parent.
 110
 111       Aspect_Ada_2005,                      -- GNAT
 112       Aspect_Ada_2012,                      -- GNAT
 113       Aspect_Asynchronous,
 114       Aspect_Atomic,
 115       Aspect_Atomic_Components,
 116       Aspect_Discard_Names,
 117       Aspect_Favor_Top_Level,               -- GNAT
 118       Aspect_Independent,
 119       Aspect_Independent_Components,
 120       Aspect_Inline,
 121       Aspect_Inline_Always,                 -- GNAT
 122       Aspect_Interrupt_Handler,
 123       Aspect_No_Return,
 124       Aspect_Pack,
 125       Aspect_Persistent_BSS,                -- GNAT
 126       Aspect_Preelaborable_Initialization,
 127       Aspect_Pure_Function,                 -- GNAT
 128       Aspect_Shared,                        -- GNAT (equivalent to Atomic)
 129       Aspect_Suppress_Debug_Info,           -- GNAT
 130       Aspect_Unchecked_Union,
 131       Aspect_Universal_Aliasing,            -- GNAT
 132       Aspect_Unmodified,                    -- GNAT
 133       Aspect_Unreferenced,                  -- GNAT
 134       Aspect_Unreferenced_Objects,          -- GNAT
 135       Aspect_Volatile,
 136       Aspect_Volatile_Components);
 137
 138    --  The following array indicates aspects that accept 'Class
 139
 140    Class_Aspect_OK : constant array (Aspect_Id) of Boolean :=
 141                        (Aspect_Invariant     => True,
 142                         Aspect_Pre           => True,
 143                         Aspect_Predicate     => True,
 144                         Aspect_Post          => True,
 145                         others               => False);
 146
 147    --  The following array identifies all implementation defined aspects
 148
 149    Impl_Defined_Aspects : constant array (Aspect_Id) of Boolean :=
 150                             (Aspect_Object_Size          => True,
 151                              Aspect_Predicate            => True,
 152                              Aspect_Test_Case            => True,
 153                              Aspect_Value_Size           => True,
 154                              Aspect_Compiler_Unit        => True,
 155                              Aspect_Preelaborate_05      => True,
 156                              Aspect_Pure_05              => True,
 157                              Aspect_Universal_Data       => True,
 158                              Aspect_Ada_2005             => True,
 159                              Aspect_Ada_2012             => True,
 160                              Aspect_Favor_Top_Level      => True,
 161                              Aspect_Inline_Always        => True,
 162                              Aspect_Persistent_BSS       => True,
 163                              Aspect_Pure_Function        => True,
 164                              Aspect_Shared               => True,
 165                              Aspect_Suppress_Debug_Info  => True,
 166                              Aspect_Universal_Aliasing   => True,
 167                              Aspect_Unmodified           => True,
 168                              Aspect_Unreferenced         => True,
 169                              Aspect_Unreferenced_Objects => True,
 170                              others                      => False);
 171
 172    --  The following array indicates aspects for which multiple occurrences of
 173    --  the same aspect attached to the same declaration are allowed.
 174
 175    No_Duplicates_Allowed : constant array (Aspect_Id) of Boolean :=
 176                              (Aspect_Test_Case => False,
 177                               others           => True);
 178
 179    --  The following subtype defines aspects corresponding to library unit
 180    --  pragmas, these can only validly appear as aspects for library units,
 181    --  and result in a corresponding pragma being inserted immediately after
 182    --  the occurrence of the aspect.
 183
 184    subtype Library_Unit_Aspects is
 185      Aspect_Id range Aspect_All_Calls_Remote .. Aspect_Universal_Data;
 186
 187    --  The following subtype defines aspects accepting an optional static
 188    --  boolean parameter indicating if the aspect should be active or
 189    --  cancelling. If the parameter is missing the effective value is True,
 190    --  enabling the aspect. If the parameter is present it must be a static
 191    --  expression of type Standard.Boolean. If the value is True, then the
 192    --  aspect is enabled. If it is False, the aspect is disabled.
 193
 194    subtype Boolean_Aspects is
 195      Aspect_Id range Aspect_Ada_2005 .. Aspect_Id'Last;
 196
 197    subtype Pre_Post_Aspects is
 198      Aspect_Id range Aspect_Post .. Aspect_Precondition;
 199
 200    --  The following type is used for indicating allowed expression forms
 201
 202    type Aspect_Expression is
 203      (Optional,               -- Optional boolean expression
 204       Expression,             -- Required expression
 205       Name);                  -- Required name
 206
 207    --  The following array indicates what argument type is required
 208
 209    Aspect_Argument : constant array (Aspect_Id) of Aspect_Expression :=
 210                        (No_Aspect                      => Optional,
 211                         Aspect_Address                 => Expression,
 212                         Aspect_Alignment               => Expression,
 213                         Aspect_Attach_Handler          => Expression,
 214                         Aspect_Bit_Order               => Expression,
 215                         Aspect_Component_Size          => Expression,
 216                         Aspect_Constant_Indexing       => Name,
 217                         Aspect_CPU                     => Expression,
 218                         Aspect_Default_Component_Value => Expression,
 219                         Aspect_Default_Iterator        => Name,
 220                         Aspect_Default_Value           => Expression,
 221                         Aspect_Dispatching_Domain      => Expression,
 222                         Aspect_Dynamic_Predicate       => Expression,
 223                         Aspect_External_Tag            => Expression,
 224                         Aspect_Implicit_Dereference    => Name,
 225                         Aspect_Input                   => Name,
 226                         Aspect_Interrupt_Priority      => Expression,
 227                         Aspect_Invariant               => Expression,
 228                         Aspect_Iterator_Element        => Name,
 229                         Aspect_Machine_Radix           => Expression,
 230                         Aspect_Object_Size             => Expression,
 231                         Aspect_Output                  => Name,
 232                         Aspect_Post                    => Expression,
 233                         Aspect_Postcondition           => Expression,
 234                         Aspect_Pre                     => Expression,
 235                         Aspect_Precondition            => Expression,
 236                         Aspect_Predicate               => Expression,
 237                         Aspect_Priority                => Expression,
 238                         Aspect_Read                    => Name,
 239                         Aspect_Size                    => Expression,
 240                         Aspect_Small                   => Expression,
 241                         Aspect_Static_Predicate        => Expression,
 242                         Aspect_Storage_Pool            => Name,
 243                         Aspect_Storage_Size            => Expression,
 244                         Aspect_Stream_Size             => Expression,
 245                         Aspect_Suppress                => Name,
 246                         Aspect_Test_Case               => Expression,
 247                         Aspect_Type_Invariant          => Expression,
 248                         Aspect_Unsuppress              => Name,
 249                         Aspect_Value_Size              => Expression,
 250                         Aspect_Variable_Indexing       => Name,
 251                         Aspect_Warnings                => Name,
 252                         Aspect_Write                   => Name,
 253
 254                         Library_Unit_Aspects           => Optional,
 255                         Boolean_Aspects                => Optional);
 256
 257    -----------------------------------------
 258    -- Table Linking Names and Aspect_Id's --
 259    -----------------------------------------
 260
 261    --  Table linking aspect names and id's
 262
 263    Aspect_Names : constant array (Aspect_Id) of Name_Id := (
 264      No_Aspect                           => No_Name,
 265      Aspect_Ada_2005                     => Name_Ada_2005,
 266      Aspect_Ada_2012                     => Name_Ada_2012,
 267      Aspect_Address                      => Name_Address,
 268      Aspect_Alignment                    => Name_Alignment,
 269      Aspect_All_Calls_Remote             => Name_All_Calls_Remote,
 270      Aspect_Asynchronous                 => Name_Asynchronous,
 271      Aspect_Atomic                       => Name_Atomic,
 272      Aspect_Atomic_Components            => Name_Atomic_Components,
 273      Aspect_Attach_Handler               => Name_Attach_Handler,
 274      Aspect_Bit_Order                    => Name_Bit_Order,
 275      Aspect_Compiler_Unit                => Name_Compiler_Unit,
 276      Aspect_Component_Size               => Name_Component_Size,
 277      Aspect_Constant_Indexing            => Name_Constant_Indexing,
 278      Aspect_CPU                          => Name_CPU,
 279      Aspect_Default_Iterator             => Name_Default_Iterator,
 280      Aspect_Default_Value                => Name_Default_Value,
 281      Aspect_Default_Component_Value      => Name_Default_Component_Value,
 282      Aspect_Discard_Names                => Name_Discard_Names,
 283      Aspect_Dispatching_Domain           => Name_Dispatching_Domain,
 284      Aspect_Dynamic_Predicate            => Name_Dynamic_Predicate,
 285      Aspect_Elaborate_Body               => Name_Elaborate_Body,
 286      Aspect_External_Tag                 => Name_External_Tag,
 287      Aspect_Favor_Top_Level              => Name_Favor_Top_Level,
 288      Aspect_Implicit_Dereference         => Name_Implicit_Dereference,
 289      Aspect_Independent                  => Name_Independent,
 290      Aspect_Independent_Components       => Name_Independent_Components,
 291      Aspect_Inline                       => Name_Inline,
 292      Aspect_Inline_Always                => Name_Inline_Always,
 293      Aspect_Input                        => Name_Input,
 294      Aspect_Interrupt_Handler            => Name_Interrupt_Handler,
 295      Aspect_Interrupt_Priority           => Name_Interrupt_Priority,
 296      Aspect_Invariant                    => Name_Invariant,
 297      Aspect_Iterator_Element             => Name_Iterator_Element,
 298      Aspect_Machine_Radix                => Name_Machine_Radix,
 299      Aspect_No_Return                    => Name_No_Return,
 300      Aspect_Object_Size                  => Name_Object_Size,
 301      Aspect_Output                       => Name_Output,
 302      Aspect_Pack                         => Name_Pack,
 303      Aspect_Persistent_BSS               => Name_Persistent_BSS,
 304      Aspect_Post                         => Name_Post,
 305      Aspect_Postcondition                => Name_Postcondition,
 306      Aspect_Pre                          => Name_Pre,
 307      Aspect_Precondition                 => Name_Precondition,
 308      Aspect_Predicate                    => Name_Predicate,
 309      Aspect_Preelaborable_Initialization => Name_Preelaborable_Initialization,
 310      Aspect_Preelaborate                 => Name_Preelaborate,
 311      Aspect_Preelaborate_05              => Name_Preelaborate_05,
 312      Aspect_Priority                     => Name_Priority,
 313      Aspect_Pure                         => Name_Pure,
 314      Aspect_Pure_05                      => Name_Pure_05,
 315      Aspect_Pure_Function                => Name_Pure_Function,
 316      Aspect_Read                         => Name_Read,
 317      Aspect_Remote_Call_Interface        => Name_Remote_Call_Interface,
 318      Aspect_Remote_Types                 => Name_Remote_Types,
 319      Aspect_Shared                       => Name_Shared,
 320      Aspect_Shared_Passive               => Name_Shared_Passive,
 321      Aspect_Size                         => Name_Size,
 322      Aspect_Small                        => Name_Small,
 323      Aspect_Static_Predicate             => Name_Static_Predicate,
 324      Aspect_Storage_Pool                 => Name_Storage_Pool,
 325      Aspect_Storage_Size                 => Name_Storage_Size,
 326      Aspect_Stream_Size                  => Name_Stream_Size,
 327      Aspect_Suppress                     => Name_Suppress,
 328      Aspect_Suppress_Debug_Info          => Name_Suppress_Debug_Info,
 329      Aspect_Test_Case                    => Name_Test_Case,
 330      Aspect_Type_Invariant               => Name_Type_Invariant,
 331      Aspect_Unchecked_Union              => Name_Unchecked_Union,
 332      Aspect_Universal_Aliasing           => Name_Universal_Aliasing,
 333      Aspect_Universal_Data               => Name_Universal_Data,
 334      Aspect_Unmodified                   => Name_Unmodified,
 335      Aspect_Unreferenced                 => Name_Unreferenced,
 336      Aspect_Unreferenced_Objects         => Name_Unreferenced_Objects,
 337      Aspect_Unsuppress                   => Name_Unsuppress,
 338      Aspect_Value_Size                   => Name_Value_Size,
 339      Aspect_Variable_Indexing            => Name_Variable_Indexing,
 340      Aspect_Volatile                     => Name_Volatile,
 341      Aspect_Volatile_Components          => Name_Volatile_Components,
 342      Aspect_Warnings                     => Name_Warnings,
 343      Aspect_Write                        => Name_Write);
 344
 345    function Get_Aspect_Id (Name : Name_Id) return Aspect_Id;
 346    pragma Inline (Get_Aspect_Id);
 347    --  Given a name Nam, returns the corresponding aspect id value. If the name
 348    --  does not match any aspect, then No_Aspect is returned as the result.
 349
 350    ---------------------------------------------------
 351    -- Handling of Aspect Specifications in the Tree --
 352    ---------------------------------------------------
 353
 354    --  Several kinds of declaration node permit aspect specifications in Ada
 355    --  2012 mode. If there was room in all the corresponding declaration nodes,
 356    --  we could just have a field Aspect_Specifications pointing to a list of
 357    --  nodes for the aspects (N_Aspect_Specification nodes). But there isn't
 358    --  room, so we adopt a different approach.
 359
 360    --  The following subprograms provide access to a specialized interface
 361    --  implemented internally with a hash table in the body, that provides
 362    --  access to aspect specifications.
 363
 364    function Permits_Aspect_Specifications (N : Node_Id) return Boolean;
 365    --  Returns True if the node N is a declaration node that permits aspect
 366    --  specifications in the grammar. It is possible for other nodes to have
 367    --  aspect specifications as a result of Rewrite or Replace calls.
 368
 369    function Aspect_Specifications (N : Node_Id) return List_Id;
 370    --  Given a node N, returns the list of N_Aspect_Specification nodes that
 371    --  are attached to this declaration node. If the node is in the class of
 372    --  declaration nodes that permit aspect specifications, as defined by the
 373    --  predicate above, and if their Has_Aspects flag is set to True, then this
 374    --  will always be a non-empty list. If this flag is set to False, then
 375    --  No_List is returned. Normally, the only nodes that have Has_Aspects set
 376    --  True are the nodes for which Permits_Aspect_Specifications would return
 377    --  True (i.e. the declaration nodes defined in the RM as permitting the
 378    --  presence of Aspect_Specifications). However, it is possible for the
 379    --  flag Has_Aspects to be set on other nodes as a result of Rewrite and
 380    --  Replace calls, and this function may be used to retrieve the aspect
 381    --  specifications for the original rewritten node in such cases.
 382
 383    procedure Set_Aspect_Specifications (N : Node_Id; L : List_Id);
 384    --  The node N must be in the class of declaration nodes that permit aspect
 385    --  specifications and the Has_Aspects flag must be False on entry. L must
 386    --  be a non-empty list of N_Aspect_Specification nodes. This procedure sets
 387    --  the Has_Aspects flag to True, and makes an entry that can be retrieved
 388    --  by a subsequent Aspect_Specifications call. It is an error to call this
 389    --  procedure with a node that does not permit aspect specifications, or a
 390    --  node that has its Has_Aspects flag set True on entry, or with L being an
 391    --  empty list or No_List.
 392
 393    function Find_Aspect (Ent : Entity_Id; A : Aspect_Id) return Node_Id;
 394    --  Find value of a given aspect from aspect list of entity
 395
 396    procedure Move_Aspects (From : Node_Id; To : Node_Id);
 397    --  Moves aspects from 'From' node to 'To' node. Has_Aspects (To) must be
 398    --  False on entry. If Has_Aspects (From) is False, the call has no effect.
 399    --  Otherwise the aspects are moved and on return Has_Aspects (To) is True,
 400    --  and Has_Aspects (From) is False.
 401
 402    function Same_Aspect (A1 : Aspect_Id; A2 : Aspect_Id) return Boolean;
 403    --  Returns True if A1 and A2 are (essentially) the same aspect. This is not
 404    --  a simple equality test because e.g. Post and Postcondition are the same.
 405    --  This is used for detecting duplicate aspects.
 406
 407    procedure Tree_Write;
 408    --  Writes contents of Aspect_Specifications hash table to the tree file
 409
 410    procedure Tree_Read;
 411    --  Reads contents of Aspect_Specifications hash table from the tree file
 412
 413 end Aspects;