| ------------------------------------------------------------------------------ |
| -- -- |
| -- GNAT COMPILER COMPONENTS -- |
| -- -- |
| -- G E N _ I L . G E N -- |
| -- -- |
| -- S p e c -- |
| -- -- |
| -- Copyright (C) 2020-2022, Free Software Foundation, Inc. -- |
| -- -- |
| -- GNAT is free software; you can redistribute it and/or modify it under -- |
| -- terms of the GNU General Public License as published by the Free Soft- -- |
| -- ware Foundation; either version 3, or (at your option) any later ver- -- |
| -- sion. GNAT is distributed in the hope that it will be useful, but WITH- -- |
| -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY -- |
| -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -- |
| -- for more details. You should have received a copy of the GNU General -- |
| -- Public License distributed with GNAT; see file COPYING3. If not, go to -- |
| -- http://www.gnu.org/licenses for a complete copy of the license. -- |
| -- -- |
| -- GNAT was originally developed by the GNAT team at New York University. -- |
| -- Extensive contributions were provided by Ada Core Technologies Inc. -- |
| -- -- |
| ------------------------------------------------------------------------------ |
| |
| -- "Language design is library design and library design is language design". |
| -- -- Bjarne Stroustrup |
| |
| -- This package provides a "little language" for defining type hierarchies, |
| -- which we call "Gen_IL.Gen". In particular, it is used to describe the type |
| -- hierarchies rooted at Node_Id and Entity_Id in the intermediate language |
| -- used by GNAT. |
| |
| -- The type hierarchy is a strict hierarchy (treeish, no multiple |
| -- inheritance). We have "abstract" and "concrete" types. Each type has a |
| -- "parent", except for the root type (Node_Id or Entity_Id). All leaf types |
| -- in the hierarchy are concrete; all nonleaf types (including the two root |
| -- types) are abstract. One can create instances of concrete, but not |
| -- abstract, types. |
| -- |
| -- Descendants of Node_Id/Node_Kind are node types, and descendants of |
| -- Entity_Id/Entity_Kind are entity types. |
| -- |
| -- Types have "fields". Each type inherits all the fields from its parent, and |
| -- may add new ones. A node field can be marked "syntactic"; entity fields are |
| -- never syntactic. A nonsyntactic field is "semantic". |
| -- |
| -- If a field is syntactic, then the constructors in Nmake take a parameter to |
| -- initialize that field. In addition, the tree-traversal routines in Atree |
| -- (Traverse_Func and Traverse_Proc) traverse syntactic fields that are of |
| -- type Node_Id (or subtypes of Node_Id) or List_Id. Finally, (with some |
| -- exceptions documented in the body) the setter for a syntactic node or list |
| -- field "Set_F (N, Val)" will set the Parent of Val to N, unless Val is Empty |
| -- or Error[_List]. |
| -- |
| -- Note that the same field can be syntactic in some node types but semantic |
| -- in other node types. This is an added complexity that we might want to |
| -- eliminate someday. We shouldn't add any new such cases. |
| -- |
| -- A "program" written in the Gen_IL.Gen language consists of calls to the |
| -- "Create_..." routines below, followed by a call to Compile, also below. In |
| -- order to understand what's going on, you need to look not only at the |
| -- Gen_IL.Gen "code", but at the output of the compiler -- at least, look at |
| -- the specs of Sinfo.Nodes and Einfo.Entities, because GNAT invokes those |
| -- directly. It's not like a normal language where you don't usually have to |
| -- look at the generated machine code. |
| -- |
| -- Thus, the Gen_IL.Gen code is really Ada code, and when you run it as an Ada |
| -- program, it generates the above-mentioned files. The program is somewhat |
| -- unusual in that it has no input. Everything it needs to generate code is |
| -- embodied in it. |
| |
| -- Why don't we just use a variant record, instead of inventing a wheel? |
| -- Or a hierarchy of tagged types? |
| -- |
| -- The key feature that Ada's variant records and tagged types lack, and that |
| -- this little language has, is that if two types have a field with the same |
| -- name, then those are the same field, even though they weren't inherited |
| -- from a common ancestor. Such fields are required to have the same type, the |
| -- same default value, and the same extra precondition. |
| |
| with Gen_IL.Types; use Gen_IL.Types; |
| pragma Warnings (Off); |
| with Gen_IL.Fields; use Gen_IL.Fields; -- for children |
| pragma Warnings (On); |
| with Gen_IL.Internals; use Gen_IL.Internals; |
| use Gen_IL.Internals.Type_Vectors; |
| use Gen_IL.Internals.Field_Vectors; |
| |
| package Gen_IL.Gen is |
| |
| procedure Create_Root_Node_Type |
| (T : Abstract_Node; |
| Fields : Field_Sequence := No_Fields) |
| with Pre => T = Node_Kind; |
| -- Create the root node type (Node_Kind), which is an abstract type |
| |
| procedure Create_Abstract_Node_Type |
| (T : Abstract_Node; Parent : Abstract_Type; |
| Fields : Field_Sequence := No_Fields); |
| -- Create an abstract node type (other than the root node type) |
| |
| procedure Create_Concrete_Node_Type |
| (T : Concrete_Node; Parent : Abstract_Type; |
| Fields : Field_Sequence := No_Fields; |
| Nmake_Assert : String := ""); |
| -- Create a concrete node type. Every node is an instance of a concrete |
| -- node type. Nmake_Assert is an assertion to put in the Make_... function |
| -- in the generated Nmake package. It should be a String that represents a |
| -- Boolean expression. |
| |
| procedure Create_Root_Entity_Type |
| (T : Abstract_Entity; |
| Fields : Field_Sequence := No_Fields) |
| with Pre => T = Entity_Kind; |
| -- Create the root entity type (Entity_Kind), which is an abstract type |
| |
| procedure Create_Abstract_Entity_Type |
| (T : Abstract_Entity; Parent : Abstract_Type; |
| Fields : Field_Sequence := No_Fields); |
| -- Create an abstract entity type (other than the root entity type) |
| |
| procedure Create_Concrete_Entity_Type |
| (T : Concrete_Entity; Parent : Abstract_Type; |
| Fields : Field_Sequence := No_Fields); |
| -- Create a concrete entity type. Every entity is an instance of a concrete |
| -- entity type. |
| |
| function Create_Syntactic_Field |
| (Field : Node_Field; |
| Field_Type : Type_Enum; |
| Default_Value : Field_Default_Value := No_Default; |
| Pre, Pre_Get, Pre_Set : String := "") return Field_Desc; |
| -- Create a syntactic field of a node type. Entities do not have syntactic |
| -- fields. |
| |
| function Create_Semantic_Field |
| (Field : Field_Enum; |
| Field_Type : Type_Enum; |
| Type_Only : Type_Only_Enum := No_Type_Only; |
| Pre, Pre_Get, Pre_Set : String := "") return Field_Desc; |
| -- Create a semantic field of a node or entity type |
| |
| -- Create_Syntactic_Field is used for syntactic fields of nodes. The order |
| -- of calls to Create_Syntactic_Field determines the order of the formal |
| -- parameters of the Make_... functions in Nmake. |
| -- |
| -- Create_Semantic_Field is used for semantic fields of nodes, and all |
| -- fields of entities are considered semantic. The order of calls doesn't |
| -- make any difference. |
| -- |
| -- Field_Type is the type of the field. Default_Value is the default value |
| -- for the parameter of the Make_... function in Nmake; this is effective |
| -- only for syntactic fields. Flag fields of syntactic nodes always have a |
| -- default value, which is False unless specified as Default_True. Pre is |
| -- an additional precondition for the field getter and setter, in addition |
| -- to the precondition that asserts that the type has that field. It should |
| -- be a String that represents a Boolean expression. Pre_Get and Pre_Set |
| -- are similar to Pre, but for the getter or setter only, respectively. |
| -- |
| -- If multiple calls to these occur for the same Field but different types, |
| -- the Field_Type, Pre, Pre_Get, and Pre_Set must match. Default_Value |
| -- should match for syntactic fields. See the declaration of Type_Only_Enum |
| -- for Type_Only. |
| -- |
| -- (The matching Default_Value requirement is a simplification from the |
| -- earlier hand-written version.) |
| |
| -- When adding new node or entity kinds, or adding new fields, all back |
| -- ends must be made aware of the changes. In addition, the documentation |
| -- in Sinfo or Einfo needs to be updated. |
| |
| -- To add a new node or entity type, add it to the enumeration type in |
| -- Gen_IL.Types, taking care that it is in the approprate range |
| -- (Abstract_Node, Abstract_Entity, Concrete_Node, or Concrete_Entity). |
| -- Then add a call to one of the above type-creation procedures to |
| -- Gen_IL.Gen.Gen_Nodes or Gen_IL.Gen.Gen_Entities. |
| -- |
| -- To add a new field to a type, add it to the enumeration type in |
| -- Gen_IL.Fields in the appropriate range. Then add a call to one of |
| -- the above field-creation procedures to Gen_IL.Gen.Gen_Nodes or |
| -- Gen_IL.Gen.Gen_Entities. |
| -- |
| -- If a type or field name does not follow the usual Mixed_Case convention, |
| -- such as "SPARK_Pragma", then you have to add a special case to one of |
| -- the Image functions in Gen_IL.Internals and in Treepr. |
| |
| -- Forward references are not allowed. So if you say: |
| -- |
| -- Create..._Type (..., Parent => P); |
| -- |
| -- then Create..._Type must have already been called to create P. |
| -- |
| -- Likewise, if you say: |
| -- |
| -- Create..._Field (T, F, Field_Type, ...); |
| -- |
| -- then Create..._Type must have already been called to create T and |
| -- (if it's a node or entity type) to create Field_Type. |
| -- |
| -- To delete a node or entity type, delete it from Gen_IL.Types, update the |
| -- subranges in Gen_IL.Internals if necessary, and delete all occurrences |
| -- from Gen_IL.Gen.Gen_Entities. To delete a field, delete it from |
| -- Gen_IL.Fields, and delete all occurrences from Gen_IL.Gen.Gen_Entities. |
| |
| -- If a field is not set, it is initialized by default to whatever value is |
| -- represented by all-zero bits, with some exceptions. This means Flags are |
| -- initialized to False, Node_Ids and List_Ids are initialized to Empty, |
| -- and enumeration fields are initialized to 'First of the type (assuming |
| -- there is no representation clause). |
| -- |
| -- Elists default to No_Elist. |
| -- |
| -- Fields of type Uint (but not its subtypes) are initialized to No_Uint. |
| -- Fields of subtypes Valid_Uint, Unat, Upos, Nonzero_Uint, and Ureal have |
| -- no default; it is an error to call a getter before calling the setter. |
| -- Likewise, other types whose range does not include zero have no default |
| -- (see package Types for the ranges). |
| -- |
| -- If a node is created by a function in Nmake, then the defaults are |
| -- different from what is specified above. The parameters of Make_... |
| -- functions can have defaults specified; see Create_Syntactic_Field. |
| |
| procedure Create_Node_Union_Type |
| (T : Abstract_Node; Children : Type_Array); |
| procedure Create_Entity_Union_Type |
| (T : Abstract_Entity; Children : Type_Array); |
| -- Create a "union" type that is the union of the Children. This is used |
| -- for nonhierachical types. This is the opposite of the normal "object |
| -- oriented" routines above, which create child types based on existing |
| -- parents. Here we are creating parent types based on existing child |
| -- types. A union type is considered to be an abstract type because it has |
| -- multiple children. We do not allow union types to have their own fields, |
| -- because that would introduce the well-known complexity of multiple |
| -- inheritance. That restriction could be relaxed, but for now, union types |
| -- are mainly for allowing things like "Pre => X in Some_Union_Type". |
| |
| Illegal : exception; |
| -- Exception raised when Gen_IL code (in particular in Gen_Nodes and |
| -- Gen_Entities) is illegal. We don't try elaborate error recovery, but |
| -- hopefully the exception message will indicate what's wrong. You might |
| -- have to go in the debugger to see which line it's complaining about. |
| |
| procedure Compile; |
| |
| private |
| |
| function Sy |
| (Field : Node_Field; |
| Field_Type : Type_Enum; |
| Default_Value : Field_Default_Value := No_Default; |
| Pre, Pre_Get, Pre_Set : String := "") return Field_Sequence; |
| function Sm |
| (Field : Field_Enum; |
| Field_Type : Type_Enum; |
| Type_Only : Type_Only_Enum := No_Type_Only; |
| Pre, Pre_Get, Pre_Set : String := "") return Field_Sequence; |
| -- The above functions return Field_Sequence. This is a trick to get around |
| -- the fact that Ada doesn't allow singleton positional aggregates. It |
| -- allows us to write things like: |
| -- |
| -- Cc (N_Empty, Node_Kind, |
| -- (Sy (Chars, Name_Id, Default_No_Name))); |
| -- |
| -- where that thing pretending to be an aggregate is really a parenthesized |
| -- expression. See Gen_Nodes for documentation of the functions these are |
| -- standing in for. |
| |
| end Gen_IL.Gen; |
