gcc/ada/gen_il-gen.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                            G E N _ I L . G E N                           --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --          Copyright (C) 2020-2023, 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.  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 COPYING3.  If not, go to --
  19 -- http://www.gnu.org/licenses for a complete copy of the license.          --
  20 --                                                                          --
  21 -- GNAT was originally developed  by the GNAT team at  New York University. --
  22 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  23 --                                                                          --
  24 ------------------------------------------------------------------------------
  25
  26 --  "Language design is library design and library design is language design".
  27 --    -- Bjarne Stroustrup
  28
  29 --  This package provides a "little language" for defining type hierarchies,
  30 --  which we call "Gen_IL.Gen". In particular, it is used to describe the type
  31 --  hierarchies rooted at Node_Id and Entity_Id in the intermediate language
  32 --  used by GNAT.
  33
  34 --  The type hierarchy is a strict hierarchy (treeish, no multiple
  35 --  inheritance). We have "abstract" and "concrete" types. Each type has a
  36 --  "parent", except for the root type (Node_Id or Entity_Id). All leaf types
  37 --  in the hierarchy are concrete; all nonleaf types (including the two root
  38 --  types) are abstract. One can create instances of concrete, but not
  39 --  abstract, types.
  40 --
  41 --  Descendants of Node_Id/Node_Kind are node types, and descendants of
  42 --  Entity_Id/Entity_Kind are entity types.
  43 --
  44 --  Types have "fields". Each type inherits all the fields from its parent, and
  45 --  may add new ones. A node field can be marked "syntactic"; entity fields are
  46 --  never syntactic. A nonsyntactic field is "semantic".
  47 --
  48 --  If a field is syntactic, then the constructors in Nmake take a parameter to
  49 --  initialize that field. In addition, the tree-traversal routines in Atree
  50 --  (Traverse_Func and Traverse_Proc) traverse syntactic fields that are of
  51 --  type Node_Id (or subtypes of Node_Id) or List_Id. Finally, (with some
  52 --  exceptions documented in the body) the setter for a syntactic node or list
  53 --  field "Set_F (N, Val)" will set the Parent of Val to N, unless Val is Empty
  54 --  or Error[_List].
  55 --
  56 --  Note that the same field can be syntactic in some node types but semantic
  57 --  in other node types. This is an added complexity that we might want to
  58 --  eliminate someday. We shouldn't add any new such cases.
  59 --
  60 --  A "program" written in the Gen_IL.Gen language consists of calls to the
  61 --  "Create_..." routines below, followed by a call to Compile, also below. In
  62 --  order to understand what's going on, you need to look not only at the
  63 --  Gen_IL.Gen "code", but at the output of the compiler -- at least, look at
  64 --  the specs of Sinfo.Nodes and Einfo.Entities, because GNAT invokes those
  65 --  directly. It's not like a normal language where you don't usually have to
  66 --  look at the generated machine code.
  67 --
  68 --  Thus, the Gen_IL.Gen code is really Ada code, and when you run it as an Ada
  69 --  program, it generates the above-mentioned files. The program is somewhat
  70 --  unusual in that it has no input. Everything it needs to generate code is
  71 --  embodied in it.
  72
  73 --  Why don't we just use a variant record, instead of inventing a wheel?
  74 --  Or a hierarchy of tagged types?
  75 --
  76 --  The key feature that Ada's variant records and tagged types lack, and that
  77 --  this little language has, is that if two types have a field with the same
  78 --  name, then those are the same field, even though they weren't inherited
  79 --  from a common ancestor. Such fields are required to have the same type, the
  80 --  same default value, and the same extra precondition.
  81
  82 with Gen_IL.Types;  use Gen_IL.Types;
  83 pragma Warnings (Off);
  84 with Gen_IL.Fields; use Gen_IL.Fields; -- for children
  85 pragma Warnings (On);
  86 with Gen_IL.Internals;  use Gen_IL.Internals;
  87 use Gen_IL.Internals.Type_Vectors;
  88 use Gen_IL.Internals.Field_Vectors;
  89
  90 package Gen_IL.Gen is
  91
  92    procedure Create_Root_Node_Type
  93      (T : Abstract_Node;
  94       Fields : Field_Sequence := No_Fields)
  95       with Pre => T = Node_Kind;
  96    --  Create the root node type (Node_Kind), which is an abstract type
  97
  98    procedure Create_Abstract_Node_Type
  99      (T : Abstract_Node; Parent : Abstract_Type;
 100       Fields : Field_Sequence := No_Fields);
 101    --  Create an abstract node type (other than the root node type)
 102
 103    procedure Create_Concrete_Node_Type
 104      (T : Concrete_Node; Parent : Abstract_Type;
 105       Fields : Field_Sequence := No_Fields;
 106       Nmake_Assert : String := "");
 107    --  Create a concrete node type. Every node is an instance of a concrete
 108    --  node type. Nmake_Assert is an assertion to put in the Make_... function
 109    --  in the generated Nmake package. It should be a String that represents a
 110    --  Boolean expression.
 111
 112    procedure Create_Root_Entity_Type
 113      (T : Abstract_Entity;
 114       Fields : Field_Sequence := No_Fields)
 115       with Pre => T = Entity_Kind;
 116    --  Create the root entity type (Entity_Kind), which is an abstract type
 117
 118    procedure Create_Abstract_Entity_Type
 119      (T : Abstract_Entity; Parent : Abstract_Type;
 120       Fields : Field_Sequence := No_Fields);
 121    --  Create an abstract entity type (other than the root entity type)
 122
 123    procedure Create_Concrete_Entity_Type
 124      (T : Concrete_Entity; Parent : Abstract_Type;
 125       Fields : Field_Sequence := No_Fields);
 126    --  Create a concrete entity type. Every entity is an instance of a concrete
 127    --  entity type.
 128
 129    function Create_Syntactic_Field
 130      (Field      : Node_Field;
 131       Field_Type : Type_Enum;
 132       Default_Value : Field_Default_Value := No_Default;
 133       Pre, Pre_Get, Pre_Set : String := "") return Field_Desc;
 134    --  Create a syntactic field of a node type. Entities do not have syntactic
 135    --  fields.
 136
 137    function Create_Semantic_Field
 138      (Field      : Field_Enum;
 139       Field_Type : Type_Enum;
 140       Type_Only  : Type_Only_Enum := No_Type_Only;
 141       Pre, Pre_Get, Pre_Set : String := "") return Field_Desc;
 142    --  Create a semantic field of a node or entity type
 143
 144    --  Create_Syntactic_Field is used for syntactic fields of nodes. The order
 145    --  of calls to Create_Syntactic_Field determines the order of the formal
 146    --  parameters of the Make_... functions in Nmake.
 147    --
 148    --  Create_Semantic_Field is used for semantic fields of nodes, and all
 149    --  fields of entities are considered semantic. The order of calls doesn't
 150    --  make any difference.
 151    --
 152    --  Field_Type is the type of the field. Default_Value is the default value
 153    --  for the parameter of the Make_... function in Nmake; this is effective
 154    --  only for syntactic fields. Flag fields of syntactic nodes always have a
 155    --  default value, which is False unless specified as Default_True. Pre is
 156    --  an additional precondition for the field getter and setter, in addition
 157    --  to the precondition that asserts that the type has that field. It should
 158    --  be a String that represents a Boolean expression. Pre_Get and Pre_Set
 159    --  are similar to Pre, but for the getter or setter only, respectively.
 160    --
 161    --  If multiple calls to these occur for the same Field but different types,
 162    --  the Field_Type, Pre, Pre_Get, and Pre_Set must match. Default_Value
 163    --  should match for syntactic fields. See the declaration of Type_Only_Enum
 164    --  for Type_Only.
 165    --
 166    --  (The matching Default_Value requirement is a simplification from the
 167    --  earlier hand-written version.)
 168
 169    --  When adding new node or entity kinds, or adding new fields, all back
 170    --  ends must be made aware of the changes. In addition, the documentation
 171    --  in Sinfo or Einfo needs to be updated.
 172
 173    --  To add a new node or entity type, add it to the enumeration type in
 174    --  Gen_IL.Types, taking care that it is in the approprate range
 175    --  (Abstract_Node, Abstract_Entity, Concrete_Node, or Concrete_Entity).
 176    --  Then add a call to one of the above type-creation procedures to
 177    --  Gen_IL.Gen.Gen_Nodes or Gen_IL.Gen.Gen_Entities.
 178    --
 179    --  To add a new field to a type, add it to the enumeration type in
 180    --  Gen_IL.Fields in the appropriate range. Then add a call to one of
 181    --  the above field-creation procedures to Gen_IL.Gen.Gen_Nodes or
 182    --  Gen_IL.Gen.Gen_Entities.
 183    --
 184    --  If a type or field name does not follow the usual Mixed_Case convention,
 185    --  such as "SPARK_Pragma", then you have to add a special case to one of
 186    --  the Image functions in Gen_IL.Internals and in Treepr.
 187
 188    --  Forward references are not allowed. So if you say:
 189    --
 190    --     Create..._Type (..., Parent => P);
 191    --
 192    --  then Create..._Type must have already been called to create P.
 193    --
 194    --  Likewise, if you say:
 195    --
 196    --     Create..._Field (T, F, Field_Type, ...);
 197    --
 198    --  then Create..._Type must have already been called to create T and
 199    --  (if it's a node or entity type) to create Field_Type.
 200    --
 201    --  To delete a node or entity type, delete it from Gen_IL.Types, update the
 202    --  subranges in Gen_IL.Internals if necessary, and delete all occurrences
 203    --  from Gen_IL.Gen.Gen_Entities. To delete a field, delete it from
 204    --  Gen_IL.Fields, and delete all occurrences from Gen_IL.Gen.Gen_Entities.
 205
 206    --  If a field is not set, it is initialized by default to whatever value is
 207    --  represented by all-zero bits, with some exceptions. This means Flags are
 208    --  initialized to False, Node_Ids and List_Ids are initialized to Empty,
 209    --  and enumeration fields are initialized to 'First of the type (assuming
 210    --  there is no representation clause).
 211    --
 212    --  Elists default to No_Elist.
 213    --
 214    --  Fields of type Uint (but not its subtypes) are initialized to No_Uint.
 215    --  Fields of subtypes Valid_Uint, Unat, Upos, Nonzero_Uint, and Ureal have
 216    --  no default; it is an error to call a getter before calling the setter.
 217    --  Likewise, other types whose range does not include zero have no default
 218    --  (see package Types for the ranges).
 219    --
 220    --  If a node is created by a function in Nmake, then the defaults are
 221    --  different from what is specified above. The parameters of Make_...
 222    --  functions can have defaults specified; see Create_Syntactic_Field.
 223
 224    procedure Create_Node_Union_Type
 225      (T : Abstract_Node; Children : Type_Array);
 226    procedure Create_Entity_Union_Type
 227      (T : Abstract_Entity; Children : Type_Array);
 228    --  Create a "union" type that is the union of the Children. This is used
 229    --  for nonhierachical types. This is the opposite of the normal "object
 230    --  oriented" routines above, which create child types based on existing
 231    --  parents. Here we are creating parent types based on existing child
 232    --  types. A union type is considered to be an abstract type because it has
 233    --  multiple children. We do not allow union types to have their own fields,
 234    --  because that would introduce the well-known complexity of multiple
 235    --  inheritance. That restriction could be relaxed, but for now, union types
 236    --  are mainly for allowing things like "Pre => X in Some_Union_Type".
 237
 238    Illegal : exception;
 239    --  Exception raised when Gen_IL code (in particular in Gen_Nodes and
 240    --  Gen_Entities) is illegal. We don't try elaborate error recovery, but
 241    --  hopefully the exception message will indicate what's wrong. You might
 242    --  have to go in the debugger to see which line it's complaining about.
 243
 244    procedure Compile;
 245
 246 private
 247
 248    function Sy
 249      (Field      : Node_Field;
 250       Field_Type : Type_Enum;
 251       Default_Value : Field_Default_Value := No_Default;
 252       Pre, Pre_Get, Pre_Set : String := "") return Field_Sequence;
 253    function Sm
 254      (Field      : Field_Enum;
 255       Field_Type : Type_Enum;
 256       Type_Only  : Type_Only_Enum := No_Type_Only;
 257       Pre, Pre_Get, Pre_Set : String := "") return Field_Sequence;
 258    --  The above functions return Field_Sequence. This is a trick to get around
 259    --  the fact that Ada doesn't allow singleton positional aggregates. It
 260    --  allows us to write things like:
 261    --
 262    --     Cc (N_Empty, Node_Kind,
 263    --         (Sy (Chars, Name_Id, Default_No_Name)));
 264    --
 265    --  where that thing pretending to be an aggregate is really a parenthesized
 266    --  expression. See Gen_Nodes for documentation of the functions these are
 267    --  standing in for.
 268
 269 end Gen_IL.Gen;