gcc/ada/sinfo-utils.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                           S I N F O . U T I L S                          --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --           Copyright (C) 2020-2021, 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 with Sinfo.Nodes; use Sinfo.Nodes;
  27
  28 package Sinfo.Utils is
  29
  30    -------------------------------
  31    -- Parent-related operations --
  32    -------------------------------
  33
  34    procedure Copy_Parent (To, From : Node_Or_Entity_Id);
  35    --  Does Set_Parent (To, Parent (From)), except that if To or From are
  36    --  empty, does nothing. If From is empty but To is not, then Parent (To)
  37    --  should already be Empty.
  38
  39    function Parent_Kind (N : Node_Id) return Node_Kind;
  40    --  Same as Nkind (Parent (N)), except if N is Empty, return N_Empty
  41
  42    -------------------------
  43    -- Iterator Procedures --
  44    -------------------------
  45
  46    --  The call to Next_xxx (N) is equivalent to N := Next_xxx (N)
  47
  48    procedure Next_Entity       (N : in out Node_Id);
  49    procedure Next_Named_Actual (N : in out Node_Id);
  50    procedure Next_Rep_Item     (N : in out Node_Id);
  51    procedure Next_Use_Clause   (N : in out Node_Id);
  52
  53    -------------------------------------------
  54    -- Miscellaneous Tree Access Subprograms --
  55    -------------------------------------------
  56
  57    function End_Location (N : Node_Id) return Source_Ptr;
  58    --  N is an N_If_Statement or N_Case_Statement node, and this function
  59    --  returns the location of the IF token in the END IF sequence by
  60    --  translating the value of the End_Span field.
  61
  62    --  WARNING: There is a matching C declaration of this subprogram in fe.h
  63
  64    procedure Set_End_Location (N : Node_Id; S : Source_Ptr);
  65    --  N is an N_If_Statement or N_Case_Statement node. This procedure sets
  66    --  the End_Span field to correspond to the given value S. In other words,
  67    --  End_Span is set to the difference between S and Sloc (N), the starting
  68    --  location.
  69
  70    function Get_Pragma_Arg (Arg : Node_Id) return Node_Id;
  71    --  Given an argument to a pragma Arg, this function returns the expression
  72    --  for the argument. This is Arg itself, or, in the case where Arg is a
  73    --  pragma argument association node, the expression from this node.
  74
  75    -----------------------
  76    -- Utility Functions --
  77    -----------------------
  78
  79    procedure Map_Pragma_Name (From, To : Name_Id);
  80    --  Used in the implementation of pragma Rename_Pragma. Maps pragma name
  81    --  From to pragma name To, so From can be used as a synonym for To.
  82
  83    Too_Many_Pragma_Mappings : exception;
  84    --  Raised if Map_Pragma_Name is called too many times. We expect that few
  85    --  programs will use it at all, and those that do will use it approximately
  86    --  once or twice.
  87
  88    function Pragma_Name (N : Node_Id) return Name_Id;
  89    --  Obtain the name of pragma N from the Chars field of its identifier. If
  90    --  the pragma has been renamed using Rename_Pragma, this routine returns
  91    --  the name of the renaming.
  92
  93    function Pragma_Name_Unmapped (N : Node_Id) return Name_Id;
  94    --  Obtain the name of pragma N from the Chars field of its identifier. This
  95    --  form of name extraction does not take into account renamings performed
  96    --  by Rename_Pragma.
  97
  98    generic
  99       with procedure Action (U : Union_Id);
 100    procedure Walk_Sinfo_Fields (N : Node_Id);
 101    --  Walk the Sinfo fields of N, for all field types that Union_Id includes,
 102    --  and call Action on each one. However, skip the Link field, which is the
 103    --  Parent, and would cause us to wander off into the weeds.
 104
 105    generic
 106       with function Transform (U : Union_Id) return Union_Id;
 107    procedure Walk_Sinfo_Fields_Pairwise (N1, N2 : Node_Id);
 108    --  Walks the Sinfo fields of N1 and N2 pairwise, calls Tranform on each N2
 109    --  field, copying the resut into the corresponding field of N1. The Nkinds
 110    --  must match. Link is skipped.
 111
 112    -------------------------------------------
 113    -- Aliases for Entity_Or_Associated_Node --
 114    -------------------------------------------
 115
 116    --  Historically, the Entity, Associated_Node, and Entity_Or_Associated_Node
 117    --  fields shared the same slot. A further complication is that there is an
 118    --  N_Has_Entity that does not include all node types that have the Entity
 119    --  field. N_Inclusive_Has_Entity are the node types that have the Entity
 120    --  field.
 121
 122    subtype N_Inclusive_Has_Entity is Node_Id with Predicate =>
 123      N_Inclusive_Has_Entity in
 124        N_Has_Entity_Id
 125        | N_Attribute_Definition_Clause_Id
 126        | N_Aspect_Specification_Id
 127        | N_Freeze_Entity_Id
 128        | N_Freeze_Generic_Entity_Id;
 129
 130    subtype N_Has_Associated_Node is Node_Id with Predicate =>
 131      N_Has_Associated_Node in
 132        N_Has_Entity_Id
 133        | N_Aggregate_Id
 134        | N_Extension_Aggregate_Id
 135        | N_Selected_Component_Id
 136        | N_Use_Package_Clause_Id;
 137
 138    function Associated_Node
 139      (N : N_Has_Associated_Node) return Node_Id
 140       renames Entity_Or_Associated_Node;
 141
 142    function Entity
 143      (N : N_Inclusive_Has_Entity) return Node_Id
 144       renames Entity_Or_Associated_Node;
 145
 146    procedure Set_Associated_Node
 147      (N : N_Has_Associated_Node; Val : Node_Id)
 148       renames Set_Entity_Or_Associated_Node;
 149
 150    procedure Set_Entity
 151      (N : N_Inclusive_Has_Entity; Val : Node_Id)
 152       renames Set_Entity_Or_Associated_Node;
 153
 154    ---------------
 155    -- Debugging --
 156    ---------------
 157
 158    procedure New_Node_Debugging_Output (N : Node_Id);
 159    pragma Inline (New_Node_Debugging_Output);
 160    --  See package body for documentation
 161
 162 end Sinfo.Utils;