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, 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_Bit_Order,
  50       Aspect_Component_Size,
  51       Aspect_Dynamic_Predicate,
  52       Aspect_External_Tag,
  53       Aspect_Input,
  54       Aspect_Invariant,
  55       Aspect_Machine_Radix,
  56       Aspect_Object_Size,                   -- GNAT
  57       Aspect_Output,
  58       Aspect_Post,
  59       Aspect_Postcondition,
  60       Aspect_Pre,
  61       Aspect_Precondition,
  62       Aspect_Predicate,                     -- GNAT
  63       Aspect_Read,
  64       Aspect_Size,
  65       Aspect_Static_Predicate,
  66       Aspect_Storage_Pool,
  67       Aspect_Storage_Size,
  68       Aspect_Stream_Size,
  69       Aspect_Suppress,
  70       Aspect_Type_Invariant,
  71       Aspect_Unsuppress,
  72       Aspect_Value_Size,                    -- GNAT
  73       Aspect_Warnings,
  74       Aspect_Write,
  75
  76       --  Remaining aspects have a static boolean value that turns the aspect
  77       --  on or off. They all correspond to pragmas, and the flag Aspect_Cancel
  78       --  is set on the pragma if the corresponding aspect is False.
  79
  80       Aspect_Ada_2005,                      -- GNAT
  81       Aspect_Ada_2012,                      -- GNAT
  82       Aspect_Atomic,
  83       Aspect_Atomic_Components,
  84       Aspect_Discard_Names,
  85       Aspect_Favor_Top_Level,               -- GNAT
  86       Aspect_Inline,
  87       Aspect_Inline_Always,                 -- GNAT
  88       Aspect_No_Return,
  89       Aspect_Pack,
  90       Aspect_Persistent_BSS,                -- GNAT
  91       Aspect_Preelaborable_Initialization,
  92       Aspect_Pure_Function,                 -- GNAT
  93       Aspect_Shared,                        -- GNAT (equivalent to Atomic)
  94       Aspect_Suppress_Debug_Info,           -- GNAT
  95       Aspect_Unchecked_Union,
  96       Aspect_Universal_Aliasing,            -- GNAT
  97       Aspect_Unmodified,                    -- GNAT
  98       Aspect_Unreferenced,                  -- GNAT
  99       Aspect_Unreferenced_Objects,          -- GNAT
 100       Aspect_Volatile,
 101       Aspect_Volatile_Components);
 102
 103    --  The following array indicates aspects that accept 'Class
 104
 105    Class_Aspect_OK : constant array (Aspect_Id) of Boolean :=
 106                        (Aspect_Invariant     => True,
 107                         Aspect_Pre           => True,
 108                         Aspect_Predicate     => True,
 109                         Aspect_Post          => True,
 110                         others               => False);
 111
 112    --  The following subtype defines aspects accepting an optional static
 113    --  boolean parameter indicating if the aspect should be active or
 114    --  cancelling. If the parameter is missing the effective value is True,
 115    --  enabling the aspect. If the parameter is present it must be a static
 116    --  expression of type Standard.Boolean. If the value is True, then the
 117    --  aspect is enabled. If it is False, the aspect is disabled.
 118
 119    subtype Boolean_Aspects is
 120      Aspect_Id range Aspect_Ada_2005 .. Aspect_Id'Last;
 121
 122    --  The following type is used for indicating allowed expression forms
 123
 124    type Aspect_Expression is
 125      (Optional,               -- Optional boolean expression
 126       Expression,             -- Required non-boolean expression
 127       Name);                  -- Required name
 128
 129    --  The following array indicates what argument type is required
 130
 131    Aspect_Argument : constant array (Aspect_Id) of Aspect_Expression :=
 132                        (No_Aspect                => Optional,
 133                         Aspect_Address           => Expression,
 134                         Aspect_Alignment         => Expression,
 135                         Aspect_Bit_Order         => Expression,
 136                         Aspect_Component_Size    => Expression,
 137                         Aspect_Dynamic_Predicate => Expression,
 138                         Aspect_External_Tag      => Expression,
 139                         Aspect_Input             => Name,
 140                         Aspect_Invariant         => Expression,
 141                         Aspect_Machine_Radix     => Expression,
 142                         Aspect_Object_Size       => Expression,
 143                         Aspect_Output            => Name,
 144                         Aspect_Post              => Expression,
 145                         Aspect_Postcondition     => Expression,
 146                         Aspect_Pre               => Expression,
 147                         Aspect_Precondition      => Expression,
 148                         Aspect_Predicate         => Expression,
 149                         Aspect_Read              => Name,
 150                         Aspect_Size              => Expression,
 151                         Aspect_Static_Predicate  => Expression,
 152                         Aspect_Storage_Pool      => Name,
 153                         Aspect_Storage_Size      => Expression,
 154                         Aspect_Stream_Size       => Expression,
 155                         Aspect_Suppress          => Name,
 156                         Aspect_Type_Invariant    => Expression,
 157                         Aspect_Unsuppress        => Name,
 158                         Aspect_Value_Size        => Expression,
 159                         Aspect_Warnings          => Name,
 160                         Aspect_Write             => Name,
 161                         Boolean_Aspects          => Optional);
 162
 163    -----------------------------------------
 164    -- Table Linking Names and Aspect_Id's --
 165    -----------------------------------------
 166
 167    type Aspect_Entry is record
 168       Nam : Name_Id;
 169       Asp : Aspect_Id;
 170    end record;
 171
 172    --  Table linking aspect names and id's
 173
 174    Aspect_Names : constant array (Integer range <>) of Aspect_Entry :=
 175     ((Name_Ada_2005,                     Aspect_Ada_2005),
 176      (Name_Ada_2012,                     Aspect_Ada_2012),
 177      (Name_Address,                      Aspect_Address),
 178      (Name_Alignment,                    Aspect_Alignment),
 179      (Name_Atomic,                       Aspect_Atomic),
 180      (Name_Atomic_Components,            Aspect_Atomic_Components),
 181      (Name_Bit_Order,                    Aspect_Bit_Order),
 182      (Name_Component_Size,               Aspect_Component_Size),
 183      (Name_Dynamic_Predicate,            Aspect_Dynamic_Predicate),
 184      (Name_Discard_Names,                Aspect_Discard_Names),
 185      (Name_External_Tag,                 Aspect_External_Tag),
 186      (Name_Favor_Top_Level,              Aspect_Favor_Top_Level),
 187      (Name_Inline,                       Aspect_Inline),
 188      (Name_Inline_Always,                Aspect_Inline_Always),
 189      (Name_Input,                        Aspect_Input),
 190      (Name_Invariant,                    Aspect_Invariant),
 191      (Name_Machine_Radix,                Aspect_Machine_Radix),
 192      (Name_Object_Size,                  Aspect_Object_Size),
 193      (Name_Output,                       Aspect_Output),
 194      (Name_Pack,                         Aspect_Pack),
 195      (Name_Persistent_BSS,               Aspect_Persistent_BSS),
 196      (Name_Post,                         Aspect_Post),
 197      (Name_Postcondition,                Aspect_Postcondition),
 198      (Name_Pre,                          Aspect_Pre),
 199      (Name_Precondition,                 Aspect_Precondition),
 200      (Name_Predicate,                    Aspect_Predicate),
 201      (Name_Preelaborable_Initialization, Aspect_Preelaborable_Initialization),
 202      (Name_Pure_Function,                Aspect_Pure_Function),
 203      (Name_Read,                         Aspect_Read),
 204      (Name_Shared,                       Aspect_Shared),
 205      (Name_Size,                         Aspect_Size),
 206      (Name_Static_Predicate,             Aspect_Static_Predicate),
 207      (Name_Storage_Pool,                 Aspect_Storage_Pool),
 208      (Name_Storage_Size,                 Aspect_Storage_Size),
 209      (Name_Stream_Size,                  Aspect_Stream_Size),
 210      (Name_Suppress,                     Aspect_Suppress),
 211      (Name_Suppress_Debug_Info,          Aspect_Suppress_Debug_Info),
 212      (Name_Type_Invariant,               Aspect_Type_Invariant),
 213      (Name_Unchecked_Union,              Aspect_Unchecked_Union),
 214      (Name_Universal_Aliasing,           Aspect_Universal_Aliasing),
 215      (Name_Unmodified,                   Aspect_Unmodified),
 216      (Name_Unreferenced,                 Aspect_Unreferenced),
 217      (Name_Unreferenced_Objects,         Aspect_Unreferenced_Objects),
 218      (Name_Unsuppress,                   Aspect_Unsuppress),
 219      (Name_Value_Size,                   Aspect_Value_Size),
 220      (Name_Volatile,                     Aspect_Volatile),
 221      (Name_Volatile_Components,          Aspect_Volatile_Components),
 222      (Name_Warnings,                     Aspect_Warnings),
 223      (Name_Write,                        Aspect_Write));
 224
 225    function Get_Aspect_Id (Name : Name_Id) return Aspect_Id;
 226    pragma Inline (Get_Aspect_Id);
 227    --  Given a name Nam, returns the corresponding aspect id value. If the name
 228    --  does not match any aspect, then No_Aspect is returned as the result.
 229
 230    ---------------------------------------------------
 231    -- Handling of Aspect Specifications in the Tree --
 232    ---------------------------------------------------
 233
 234    --  Several kinds of declaration node permit aspect specifications in Ada
 235    --  2012 mode. If there was room in all the corresponding declaration nodes,
 236    --  we could just have a field Aspect_Specifications pointing to a list of
 237    --  nodes for the aspects (N_Aspect_Specification nodes). But there isn't
 238    --  room, so we adopt a different approach.
 239
 240    --  The following subprograms provide access to a specialized interface
 241    --  implemented internally with a hash table in the body, that provides
 242    --  access to aspect specifications.
 243
 244    function Permits_Aspect_Specifications (N : Node_Id) return Boolean;
 245    --  Returns True if the node N is a declaration node that permits aspect
 246    --  specifications in the grammar. It is possible for other nodes to have
 247    --  aspect specifications as a result of Rewrite or Replace calls.
 248
 249    function Aspect_Specifications (N : Node_Id) return List_Id;
 250    --  Given a node N, returns the list of N_Aspect_Specification nodes that
 251    --  are attached to this declaration node. If the node is in the class of
 252    --  declaration nodes that permit aspect specifications, as defined by the
 253    --  predicate above, and if their Has_Aspects flag is set to True, then this
 254    --  will always be a non-empty list. If this flag is set to False, then
 255    --  No_List is returned. Normally, the only nodes that have Has_Aspects set
 256    --  True are the nodes for which Permits_Aspect_Specifications would return
 257    --  True (i.e. the declaration nodes defined in the RM as permitting the
 258    --  presence of Aspect_Specifications). However, it is possible for the
 259    --  flag Has_Aspects to be set on other nodes as a result of Rewrite and
 260    --  Replace calls, and this function may be used to retrieve the aspect
 261    --  specifications for the original rewritten node in such cases.
 262
 263    procedure Set_Aspect_Specifications (N : Node_Id; L : List_Id);
 264    --  The node N must be in the class of declaration nodes that permit aspect
 265    --  specifications and the Has_Aspects flag must be False on entry. L must
 266    --  be a non-empty list of N_Aspect_Specification nodes. This procedure sets
 267    --  the Has_Aspects flag to True, and makes an entry that can be retrieved
 268    --  by a subsequent Aspect_Specifications call. It is an error to call this
 269    --  procedure with a node that does not permit aspect specifications, or a
 270    --  node that has its Has_Aspects flag set True on entry, or with L being an
 271    --  empty list or No_List.
 272
 273    procedure Move_Aspects (From : Node_Id; To : Node_Id);
 274    --  Moves aspects from 'From' node to 'To' node. Has_Aspects (To) must be
 275    --  False on entry. If Has_Aspects (From) is False, the call has no effect.
 276    --  Otherwise the aspects are moved and on return Has_Aspects (To) is True,
 277    --  and Has_Aspects (From) is False.
 278
 279    function Same_Aspect (A1 : Aspect_Id; A2 : Aspect_Id) return Boolean;
 280    --  Returns True if A1 and A2 are (essentially) the same aspect. This is not
 281    --  a simple equality test because e.g. Post and Postcondition are the same.
 282    --  This is used for detecting duplicate aspects.
 283
 284    procedure Tree_Write;
 285    --  Writes contents of Aspect_Specifications hash table to the tree file
 286
 287    procedure Tree_Read;
 288    --  Reads contents of Aspect_Specifications hash table from the tree file
 289
 290 end Aspects;