1------------------------------------------------------------------------------ 2-- -- 3-- GNAT COMPILER COMPONENTS -- 4-- -- 5-- E X P A N D E R -- 6-- -- 7-- S p e c -- 8-- -- 9-- Copyright (C) 1992-2013, 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 procedure performs any required expansion for the specified node. 27-- The argument is the node that is a candidate for possible expansion. 28-- If no expansion is required, then Expand returns without doing anything. 29 30-- If the node does need expansion, then the subtree is replaced by the 31-- tree corresponding to the required rewriting. This tree is a syntactic 32-- tree, except that all Entity fields must be correctly set on all 33-- direct names, since the expander presumably knows what it wants, and in 34-- any case it doesn't work to have the semantic analyzer perform visibility 35-- analysis on these trees (they may have references to non-visible runtime 36-- routines etc.) There are a few exceptions to this rule in special cases, 37-- but they must be documented clearly. 38 39-- Expand is called in two different situations: 40 41-- Nodes that are not subexpressions (Nkind not in N_Subexpr) 42 43-- In this case, Expand is called from the body of Sem, immediately 44-- after completing semantic analysis by calling the corresponding 45-- Analyze_N_xxx procedure. If expansion occurs, the given node must 46-- be replaced with another node that is also not a subexpression. 47-- This seems naturally to be the case, since it is hard to imagine any 48-- situation in which it would make sense to replace a non-expression 49-- subtree with an expression. Once the substitution is completed, the 50-- Expand routine must call Analyze on the resulting node to do any 51-- required semantic analysis. Note that references to children copied 52-- from the old tree won't be reanalyzed, since their Analyzed flag 53-- is set. 54 55-- Nodes that are subexpressions (Nkind in N_Subexpr) 56 57-- In this case, Expand is called from Sem_Res.Resolve after completing 58-- the resolution of the subexpression (this means that the expander sees 59-- the fully typed subtree). If expansion occurs, the given node must be 60-- replaced by a node that is also a subexpression. Again it is hard 61-- to see how this restriction could possibly be violated. Once the 62-- substitution is completed, the Expand routine must first call Analyze 63-- on the resulting node to do any required semantic analysis, and then 64-- call Resolve on the node to set the type (typically the type will be 65-- the same as the original type of the input node, but this is not 66-- always the case). 67 68-- In both these cases, Replace or Rewrite must be used to achieve the 69-- of the node, since the Expander routine is only passed the Node_Id 70-- of the node to be expanded, and the resulting expanded Node_Id must 71-- be the same (the parameter to Expand is mode in, not mode in-out). 72 73-- For nodes other than subexpressions, it is not necessary to preserve the 74-- original tree in the Expand routines, unlike the case for modifications 75-- to the tree made in the semantic analyzer. This is because anyone who is 76-- interested in working with the original tree (like ASIS) is required to 77-- compile in semantics checks only mode. Thus Replace may be freely used 78-- in such instances. 79 80-- For subexpressions, preservation of the original tree is required because 81-- of the need for conformance checking of default expressions, which occurs 82-- on expanded trees. This means that Replace should not ever be used on 83-- on subexpression nodes. Instead use Rewrite. 84 85-- Note: the front end avoids calls to any of the expand routines if code 86-- is not being generated. This is done for three reasons: 87 88-- 1. Make sure tree does not get mucked up by the expander if no 89-- code is being generated, and is thus usable by ASIS etc. 90 91-- 2. Save time, since expansion is not needed if a compilation is 92-- being done only to check the semantics, or if code generation 93-- has been canceled due to previously detected errors. 94 95-- 3. Allow the expand routines to assume that the tree is error free. 96-- This results from the fact that code generation mode is always 97-- cancelled when any error occurs. 98 99-- If we ever decide to implement a feature allowing object modules to be 100-- generated even if errors have been detected, then point 3 will no longer 101-- hold, and the expand routines will have to be modified to operate properly 102-- in the presence of errors (for many reasons this is not currently true). 103 104-- Note: a consequence of this approach is that error messages must never 105-- be generated in the expander, since this would mean that such error 106-- messages are not generated when the expander is not being called. 107 108-- Expansion is the last stage of analyzing a node, so Expand sets the 109-- Analyzed flag of the node being analyzed as its last action. This is 110-- done even if expansion is off (in this case, the only effect of the 111-- call to Expand is to set the Analyzed flag to True). 112 113with Types; use Types; 114 115package Expander is 116 117 -- The flag Opt.Expander_Active controls whether expansion is active 118 -- (True) or deactivated (False). When expansion is deactivated all 119 -- calls to expander routines have no effect. To temporarily disable 120 -- expansion, always call the routines defined below, do NOT change 121 -- Expander_Active directly. 122 -- 123 -- You should not use this flag to test if you are currently processing 124 -- a generic spec or body. Use the flag Inside_A_Generic instead (see 125 -- the spec of package Sem). 126 -- 127 -- There is no good reason for permanently changing the value of this flag 128 -- except after detecting a syntactic or semantic error. In this event 129 -- this flag is set to False to disable all subsequent expansion activity. 130 -- 131 -- In general this flag should be used as a read only value. The only 132 -- exceptions where it makes sense to temporarily change its value are: 133 -- 134 -- (a) when starting/completing the processing of a generic definition 135 -- or declaration (see routines Start_Generic_Processing and 136 -- End_Generic_Processing in Sem_Ch12) 137 -- 138 -- (b) when starting/completing the pre-analysis of an expression 139 -- (see the spec of package Sem for more info on pre-analysis.) 140 -- 141 -- Note that when processing a spec expression (In_Spec_Expression 142 -- is True) or performing semantic analysis of a generic spec or body 143 -- (Inside_A_Generic) or when performing pre-analysis (Full_Analysis is 144 -- False) the Expander_Active flag is False. 145 146 procedure Expand (N : Node_Id); 147 -- Expand node N, as described above 148 149 procedure Expander_Mode_Save_And_Set (Status : Boolean); 150 -- Saves the current setting of the Expander_Active flag on an internal 151 -- stack and then sets the flag to the given value. 152 -- 153 -- Note: this routine has no effect in ASIS and GNATprove modes. In ASIS 154 -- mode, all expansion activity is always off, since we want the original 155 -- semantic tree for ASIS purposes without any expansion. In GNATprove 156 -- mode, a very light expansion is performed on specific nodes. Both are 157 -- achieved by setting Expander_Active False in ASIS and GNATprove modes. 158 -- In situations such as the call to Instantiate_Bodies in Frontend, 159 -- Expander_Mode_Save_And_Set may be called to temporarily turn the 160 -- expander on, but this will have no effect in ASIS and GNATprove modes. 161 162 procedure Expander_Mode_Restore; 163 -- Restores the setting of the Expander_Active flag using the top entry 164 -- pushed onto the stack by Expander_Mode_Save_And_Reset, popping the 165 -- stack, except that if any errors have been detected, then the state of 166 -- the flag is left set to False. Disabled for ASIS and GNATprove modes 167 -- (see above). 168 169end Expander; 170