File : sem_dim.ads
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT COMPILER COMPONENTS --
4 -- --
5 -- S E M _ D I M --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 2011-2016, 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 -- This package provides support for numerical systems with dimensions. A
27 -- "dimension" is a compile-time property of a numerical type which represents
28 -- a relation between various quantifiers such as length, velocity, etc.
29
30 -- Package System.Dim.Mks offers a ready-to-use system of SI base units. In
31 -- addition, the implementation of this feature offers the ability to define
32 -- an arbitrary system of units through the use of Ada 2012 aspects.
33
34 -- Dimensionality checking is part of type analysis performed by the compiler.
35 -- It ensures that manipulation of quantified numeric values is sensible with
36 -- respect to the system of units.
37
38 -----------------------------
39 -- Aspect_Dimension_System --
40 -----------------------------
41
42 -- In order to enable the user to create their own dimension system, a new
43 -- aspect: Aspect_Dimension_System has been created.
44
45 -- Note that this aspect applies for type declaration of type derived from any
46 -- numeric type.
47
48 -- It defines the names of each dimension
49
50 ----------------------
51 -- Aspect_Dimension --
52 ----------------------
53
54 -- This new aspect applies for subtype and object declarations in order to
55 -- define new dimensions.
56
57 -- Using this aspect, the user is able to create new subtype/object with any
58 -- dimension needed.
59
60 -- Note that the base type of the subtype/object must be the type that defines
61 -- the corresponding dimension system.
62
63 -- The expression of this aspect is an aggregate of rational values for each
64 -- dimension in the corresponding dimension system.
65
66 -------------------------------------------
67 -- Dimensionality checking & propagation --
68 -------------------------------------------
69
70 -- For each node (when needed), a dimension analysis (Analyze_Dimension) is
71 -- performed as part of the Resolution routine or the Analysis routine if no
72 -- Resolution.
73
74 -- The dimension analysis is divided into two phases:
75
76 -- Phase 1: dimension checking
77
78 -- Phase 2: propagation of dimensions
79
80 -- Depending on the node kind, either none, one phase or two phases are
81 -- executed.
82
83 -- Phase 2 is called only when the node allows a dimension (see body of
84 -- Sem_Dim to get the list of nodes that permit dimensions).
85
86 with Types; use Types;
87
88 package Sem_Dim is
89
90 procedure Analyze_Aspect_Dimension
91 (N : Node_Id;
92 Id : Entity_Id;
93 Aggr : Node_Id);
94 -- Analyze the contents of aspect Dimension. Associate the provided values
95 -- and quantifiers with the related context N. Id is the corresponding
96 -- Aspect_Id (Aspect_Dimension) Aggr is the corresponding expression for
97 -- the aspect Dimension declared by the declaration of N.
98
99 procedure Analyze_Aspect_Dimension_System
100 (N : Node_Id;
101 Id : Entity_Id;
102 Aggr : Node_Id);
103 -- Analyze the contents of aspect Dimension_System. Extract the numerical
104 -- type, unit name and corresponding symbol from each indivitual dimension.
105 -- Id is the corresponding Aspect_Id (Aspect_Dimension_System). Aggr is
106 -- the corresponding expression for the aspect Dimension_System from the
107 -- declaration of N.
108
109 procedure Analyze_Dimension (N : Node_Id);
110 -- N may denote any of the following contexts:
111 -- * aggregate
112 -- * assignment statement
113 -- * attribute reference
114 -- * binary operator
115 -- * call
116 -- * compontent declaration
117 -- * extended return statement
118 -- * expanded name
119 -- * explicit dereference
120 -- * identifier
121 -- * indexed component
122 -- * number declaration
123 -- * object declaration
124 -- * object renaming declaration
125 -- * procedure call statement
126 -- * qualified expression
127 -- * selected component
128 -- * simple return statement
129 -- * slice
130 -- * subtype declaration
131 -- * type conversion
132 -- * unary operator
133 -- * unchecked type conversion
134 -- Depending on the context, ensure that all expressions and entities
135 -- involved do not violate the rules of a system.
136
137 procedure Analyze_Dimension_Array_Aggregate
138 (N : Node_Id;
139 Comp_Typ : Entity_Id);
140 -- Check, for each component of the array aggregate denoted by N, the
141 -- dimensions of the component expression match the dimensions of the
142 -- component type Comp_Typ.
143
144 procedure Analyze_Dimension_Call (N : Node_Id; Nam : Entity_Id);
145 -- This routine is split in two steps. Note the second step applies only to
146 -- function calls.
147 -- Step 1. Dimension checking:
148 -- * General case: check the dimensions of each actual parameter match
149 -- the dimensions of the corresponding formal parameter.
150 -- * Elementary function case: check each actual is dimensionless except
151 -- for Sqrt call.
152 -- Step 2. Dimension propagation (only for functions):
153 -- * General case: propagate the dimensions from the returned type to the
154 -- function call.
155 -- * Sqrt case: the resulting dimensions equal to half the dimensions of
156 -- the actual
157
158 procedure Analyze_Dimension_Extension_Or_Record_Aggregate (N : Node_Id);
159 -- Check, for each component of the extension or record aggregate denoted
160 -- by N, the dimensions of the component expression match the dimensions of
161 -- the component type.
162
163 procedure Analyze_Dimension_Formals (N : Node_Id; Formals : List_Id);
164 -- For sub spec N, issue a warning for each dimensioned formal with a
165 -- literal default value in the list of formals Formals.
166
167 procedure Check_Expression_Dimensions
168 (Expr : Node_Id;
169 Typ : Entity_Id);
170 -- Compute dimensions of a floating-point expression and compare them with
171 -- the dimensions of a the given type. Used to verify dimensions of the
172 -- components of a multidimensional array type, for which components are
173 -- typically themselves arrays. The resolution of such arrays delays the
174 -- resolution of the ultimate components to a separate phase, which forces
175 -- this separate dimension verification.
176
177 procedure Copy_Dimensions (From, To : Node_Id);
178 -- Copy dimension vector of node From to node To. Note that To must be a
179 -- node that is allowed to contain a dimension (see OK_For_Dimension in
180 -- body of Sem_Dim).
181
182 procedure Eval_Op_Expon_For_Dimensioned_Type
183 (N : Node_Id;
184 Btyp : Entity_Id);
185 -- Evaluate the Expon operator for dimensioned type with rational exponent.
186 -- Indeed the regular Eval_Op_Expon routine (see package Sem_Eval) is
187 -- restricted to Integer exponent. This routine deals only with rational
188 -- exponent which is not an integer if Btyp is a dimensioned type.
189
190 procedure Expand_Put_Call_With_Symbol (N : Node_Id);
191 -- Determine whether N denotes a subprogram call to one of the routines
192 -- defined in System.Dim.Float_IO or System.Dim.Integer_IO and add an
193 -- extra actual to the call to represent the symbolic representation of
194 -- a dimension.
195
196 function Has_Dimension_System (Typ : Entity_Id) return Boolean;
197 -- Return True if type Typ has aspect Dimension_System applied to it
198
199 function Is_Dim_IO_Package_Instantiation (N : Node_Id) return Boolean;
200 -- Return True if N is a package instantiation of System.Dim.Integer_IO or
201 -- of System.Dim.Float_IO.
202
203 procedure Remove_Dimension_In_Statement (Stmt : Node_Id);
204 -- Remove the dimensions associated with Stmt
205
206 end Sem_Dim;