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-2012, 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
86with Types; use Types;
87
88package 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)
106   --  Aggr is the corresponding expression for the aspect Dimension_System
107   --  declared by the 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   --    * identifier
120   --    * indexed component
121   --    * object declaration
122   --    * object renaming declaration
123   --    * procedure call statement
124   --    * qualified expression
125   --    * selected component
126   --    * simple return statement
127   --    * slice
128   --    * subtype declaration
129   --    * type conversion
130   --    * unary operator
131   --    * unchecked type conversion
132   --  Depending on the context, ensure that all expressions and entities
133   --  involved do not violate the rules of a system.
134
135   procedure Analyze_Dimension_Array_Aggregate
136     (N        : Node_Id;
137      Comp_Typ : Entity_Id);
138   --  Check, for each component of the array aggregate denoted by N, the
139   --  dimensions of the component expression match the dimensions of the
140   --  component type Comp_Typ.
141
142   procedure Analyze_Dimension_Call (N : Node_Id; Nam : Entity_Id);
143   --  This routine is split in two steps. Note the second step applies only to
144   --  function calls.
145   --  Step 1. Dimension checking:
146   --    * General case: check the dimensions of each actual parameter match
147   --      the dimensions of the corresponding formal parameter.
148   --    * Elementary function case: check each actual is dimensionless except
149   --      for Sqrt call.
150   --  Step 2. Dimension propagation (only for functions):
151   --    * General case: propagate the dimensions from the returned type to the
152   --      function call.
153   --    * Sqrt case: the resulting dimensions equal to half the dimensions of
154   --      the actual
155
156   procedure Analyze_Dimension_Extension_Or_Record_Aggregate (N : Node_Id);
157   --  Check, for each component of the extension or record aggregate denoted
158   --  by N, the dimensions of the component expression match the dimensions of
159   --  the component type.
160
161   procedure Analyze_Dimension_Formals (N : Node_Id; Formals : List_Id);
162   --  For sub spec N, issue a warning for each dimensioned formal with a
163   --  literal default value in the list of formals Formals.
164
165   procedure Copy_Dimensions (From, To : Node_Id);
166   --  Copy dimension vector of node From to node To. Note that To must be a
167   --  node that is allowed to contain a dimension (see OK_For_Dimension in
168   --  body of Sem_Dim).
169
170   procedure Eval_Op_Expon_For_Dimensioned_Type
171     (N    : Node_Id;
172      Btyp : Entity_Id);
173   --  Evaluate the Expon operator for dimensioned type with rational exponent.
174   --  Indeed the regular Eval_Op_Expon routine (see package Sem_Eval) is
175   --  restricted to Integer exponent. This routine deals only with rational
176   --  exponent which is not an integer if Btyp is a dimensioned type.
177
178   procedure Expand_Put_Call_With_Symbol (N : Node_Id);
179   --  Determine whether N denotes a subprogram call to one of the routines
180   --  defined in System.Dim.Float_IO or System.Dim.Integer_IO and add an
181   --  extra actual to the call to represent the symbolic representation of
182   --  a dimension.
183
184   function Has_Dimension_System (Typ : Entity_Id) return Boolean;
185   --  Return True if type Typ has aspect Dimension_System applied to it
186
187   function Is_Dim_IO_Package_Instantiation (N : Node_Id) return Boolean;
188   --  Return True if N is a package instantiation of System.Dim.Integer_IO or
189   --  of System.Dim.Float_IO.
190
191   procedure Remove_Dimension_In_Statement (Stmt : Node_Id);
192   --  Remove the dimensions associated with Stmt
193
194end Sem_Dim;
195