gcc/ada/exp_put_image.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                        E X P _ P U T _ I M A G E                         --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --             Copyright (C) 2020-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 Types; use Types;
  27
  28 package Exp_Put_Image is
  29
  30    --  Routines to build Put_Image calls. See Ada.Strings.Text_Buffers.Utils
  31    --  and System.Put_Images for the run-time routines we are generating calls
  32    --  to.
  33
  34    --  For a call to T'Put_Image, if T is elementary, we expand the code
  35    --  inline. If T is a tagged type, then Put_Image is a primitive procedure
  36    --  of T, and can be dispatched to in the class-wide case. For untagged
  37    --  composite types, we generate a procedure the first time we see a call,
  38    --  and call it. Subsequent calls call the same procedure. Thus, if there
  39    --  are calls to T'Put_Image in different units, there will be duplicates;
  40    --  each unit will get a copy of the T'Put_Image procedure.
  41
  42    function Enable_Put_Image (Typ : Entity_Id) return Boolean;
  43    --  True if the predefined Put_Image should be enabled for type T. Put_Image
  44    --  is always enabled if there is a user-specified one.
  45
  46    function Build_Put_Image_Profile
  47      (Loc : Source_Ptr; Typ : Entity_Id) return List_Id;
  48    --  Builds the parameter profile for Put_Image. This is used for the tagged
  49    --  case to build the spec for the primitive operation.
  50
  51    --  In the following Build_... routines, N is the attribute reference node,
  52    --  from which the procedure to call and the parameters to pass can be
  53    --  determined.
  54
  55    function Build_Elementary_Put_Image_Call (N : Node_Id) return Node_Id;
  56    --  Builds a Put_Image call for an elementary type.
  57
  58    function Build_String_Put_Image_Call (N : Node_Id) return Node_Id;
  59    --  Builds a Put_Image call for a standard string type.
  60
  61    function Build_Protected_Put_Image_Call (N : Node_Id) return Node_Id;
  62    --  Builds a Put_Image call for a protected type.
  63
  64    function Build_Task_Put_Image_Call (N : Node_Id) return Node_Id;
  65    --  Builds a Put_Image call for a task type.
  66
  67    --  The following routines build the Put_Image procedure for composite
  68    --  types. Typ is the base type to which the procedure applies (i.e. the
  69    --  base type of the Put_Image attribute prefix). The returned results are
  70    --  the declaration and name (entity) of the procedure.
  71
  72    procedure Build_Array_Put_Image_Procedure
  73      (Nod  : Node_Id;
  74       Typ  : Entity_Id;
  75       Decl : out Node_Id;
  76       Pnam : out Entity_Id);
  77    --  Nod provides the Sloc value for the generated code
  78
  79    procedure Build_Record_Put_Image_Procedure
  80      (Loc  : Source_Ptr;
  81       Typ  : Entity_Id;
  82       Decl : out Node_Id;
  83       Pnam : out Entity_Id);
  84    --  Loc is the location of the subprogram declaration
  85
  86    function Build_Unknown_Put_Image_Call (N : Node_Id) return Node_Id;
  87    --  Build a call to Put_Image_Unknown
  88
  89    function Image_Should_Call_Put_Image (N : Node_Id) return Boolean;
  90    --  True if T'Image should call T'Put_Image. N is the attribute_reference
  91    --  T'Image.
  92
  93    function Build_Image_Call (N : Node_Id) return Node_Id;
  94    --  N is a call to T'[[Wide_]Wide_]Image, and this translates it into the
  95    --  appropriate code to call T'Put_Image into a buffer and then extract the
  96    --  [[wide] wide] string from the buffer.
  97
  98    procedure Preload_Root_Buffer_Type (Compilation_Unit : Node_Id);
  99    --  Call RTE (RE_Root_Buffer_Type) if necessary, to load the packages
 100    --  involved in Put_Image. We need to do this explicitly, fairly early
 101    --  during compilation, because otherwise it happens during freezing, which
 102    --  triggers visibility bugs in generic instantiations.
 103
 104 end Exp_Put_Image;