gcc/ada/expander.ads

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