gcc/ada/uname.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                                U N A M E                                 --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --          Copyright (C) 1992-2023, 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 Namet; use Namet;
  27 with Types; use Types;
  28
  29 package Uname is
  30
  31    ---------------------------
  32    -- Unit Name Conventions --
  33    ---------------------------
  34
  35    --  Units are associated with a unique ASCII name as follows. First we have
  36    --  the fully expanded name of the unit, with lower case letters (except
  37    --  for the use of upper case letters for encoding upper half and wide
  38    --  characters, as described in Namet), and periods. Following this is one
  39    --  of the following suffixes:
  40
  41    --    %s  for package/subprogram/generic declarations (specs)
  42    --    %b  for package/subprogram/generic bodies and subunits
  43
  44    --  Unit names are stored in the names table, and referred to by the
  45    --  corresponding Name_Id values. The type Unit_Name_Type, derived from
  46    --  Name_Id, is used to indicate that a Name_Id value that holds a unit name
  47    --  (as defined above) is expected.
  48
  49    --  Note: as far as possible the conventions for unit names are encapsulated
  50    --  in this package. The one exception is that package Fname, which provides
  51    --  conversion routines from unit names to file names must be aware of the
  52    --  precise conventions that are used.
  53
  54    -------------------
  55    -- Display Names --
  56    -------------------
  57
  58    --  For display purposes, unit names are printed out with the suffix
  59    --  " (body)" for a body and " (spec)" for a spec. These formats are
  60    --  used for Write_Unit_Name and Get_Unit_Name_String.
  61
  62    -----------------
  63    -- Subprograms --
  64    -----------------
  65
  66    function Get_Body_Name (N : Unit_Name_Type) return Unit_Name_Type;
  67    --  Given the name of a spec, this function returns the name of the
  68    --  corresponding body, i.e. characters %s replaced by %b
  69
  70    function Get_Parent_Body_Name (N : Unit_Name_Type) return Unit_Name_Type;
  71    --  Given the name of a subunit, returns the name of the parent body
  72
  73    function Get_Parent_Spec_Name (N : Unit_Name_Type) return Unit_Name_Type;
  74    --  Given the name of a child unit spec or body, returns the unit name
  75    --  of the parent spec. Returns No_Name if the given name is not the name
  76    --  of a child unit.
  77
  78    procedure Get_External_Unit_Name_String (N : Unit_Name_Type);
  79    --  Given the name of a body or spec unit, this procedure places in
  80    --  Name_Buffer the name of the unit with periods replaced by double
  81    --  underscores. The spec/body indication is eliminated. The length
  82    --  of the stored name is placed in Name_Len. All letters are lower
  83    --  case, corresponding to the string used in external names.
  84
  85    function Get_Spec_Name (N : Unit_Name_Type) return Unit_Name_Type;
  86    --  Given the name of a body, this function returns the name of the
  87    --  corresponding spec, i.e. characters %b replaced by %s
  88
  89    function Get_Unit_Name (N : Node_Id) return Unit_Name_Type;
  90    --  This procedure returns the unit name that corresponds to the given node,
  91    --  which is one of the following:
  92    --
  93    --    N_Subprogram_Declaration         (spec) cases
  94    --    N_Package_Declaration
  95    --    N_Generic_Declaration
  96    --    N_With_Clause
  97    --    N_Function_Instantiation
  98    --    N_Package_Instantiation
  99    --    N_Procedure_Instantiation
 100    --    N_Pragma (Elaborate case)
 101    --
 102    --    N_Package_Body                   (body) cases
 103    --    N_Subprogram_Body
 104    --    N_Identifier
 105    --    N_Selected_Component
 106    --
 107    --    N_Subprogram_Body_Stub           (subunit) cases
 108    --    N_Package_Body_Stub
 109    --    N_Task_Body_Stub
 110    --    N_Protected_Body_Stub
 111    --    N_Subunit
 112
 113    procedure Get_Unit_Name_String
 114      (Buf    : in out Bounded_String;
 115       N      : Unit_Name_Type;
 116       Suffix : Boolean := True);
 117    --  Puts the display name for N in Buf. The name is decoded and contains an
 118    --  indication of spec or body if Suffix is True.
 119
 120    function Is_Body_Name (N : Unit_Name_Type) return Boolean;
 121    --  Returns True iff the given name is the unit name of a body (i.e. if
 122    --  it ends with the characters %b).
 123
 124    function Is_Child_Name (N : Unit_Name_Type) return Boolean;
 125    --  Returns True iff the given name is a child unit name (of either a
 126    --  body or a spec).
 127
 128    function Is_Internal_Unit_Name
 129      (Name               : String;
 130       Renamings_Included : Boolean := True) return Boolean;
 131    --  Same as Fname.Is_Internal_File_Name, except it works with the name of
 132    --  the unit, rather than the file name.
 133
 134    function Is_Predefined_Unit_Name
 135      (Name               : String;
 136       Renamings_Included : Boolean := True) return Boolean;
 137    --  Same as Fname.Is_Predefined_File_Name, except it works with the name of
 138    --  the unit, rather than the file name.
 139
 140    function Is_Spec_Name (N : Unit_Name_Type) return Boolean;
 141    --  Returns True iff the given name is the unit name of a specification
 142    --  (i.e. if it ends with the characters %s).
 143
 144    function Name_To_Unit_Name (N : Name_Id) return Unit_Name_Type;
 145    --  Given the Id of the Ada name of a unit, this function returns the
 146    --  corresponding unit name of the spec (by appending %s to the name).
 147
 148    function New_Child
 149      (Old  : Unit_Name_Type;
 150       Newp : Unit_Name_Type) return Unit_Name_Type;
 151    --   Old is a child unit name (for either a body or spec). Newp is the unit
 152    --   name of the actual parent (this may be different from the parent in
 153    --   old). The returned unit name is formed by taking the parent name from
 154    --   Newp and the child unit name from Old, with the result being a body or
 155    --   spec depending on Old. For example:
 156    --
 157    --     Old    = A.B.C (body)
 158    --     Newp   = A.R (spec)
 159    --     result = A.R.C (body)
 160    --
 161    --   See spec of Load_Unit for extensive discussion of why this routine
 162    --   needs to be used (the calls in Load_Unit are the only ones).
 163
 164    function Uname_Ge (Left, Right : Unit_Name_Type) return Boolean;
 165    function Uname_Gt (Left, Right : Unit_Name_Type) return Boolean;
 166    function Uname_Le (Left, Right : Unit_Name_Type) return Boolean;
 167    function Uname_Lt (Left, Right : Unit_Name_Type) return Boolean;
 168    --  These functions perform lexicographic ordering of unit names. The
 169    --  ordering is suitable for printing, and is not quite a straightforward
 170    --  comparison of the names, since the convention is that specs appear
 171    --  before bodies. Note that the standard = and /= operators work fine
 172    --  because all unit names are hashed into the name table, so if two names
 173    --  are the same, they always have the same Name_Id value.
 174
 175    procedure Write_Unit_Name (N : Unit_Name_Type);
 176    --  Writes the display form of N to standard output
 177
 178    procedure Write_Unit_Name_For_Debug (N : Unit_Name_Type);
 179    --  Like Write_Unit_Name, except it tries to be robust in the presence of
 180    --  invalid data.
 181
 182 end Uname;