gcc/ada/prj-util.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                              P R J . U T I L                             --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --          Copyright (C) 2001-2008, 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 --  Utilities for use in processing project files
  27
  28 package Prj.Util is
  29
  30    --  ??? throughout this spec, parameters are not well enough documented
  31
  32    function Executable_Of
  33      (Project  : Project_Id;
  34       In_Tree  : Project_Tree_Ref;
  35       Main     : File_Name_Type;
  36       Index    : Int;
  37       Ada_Main : Boolean := True;
  38       Language : String := "") return File_Name_Type;
  39    --  Return the value of the attribute Builder'Executable for file Main in
  40    --  the project Project, if it exists. If there is no attribute Executable
  41    --  for Main, remove the suffix from Main; then, if the attribute
  42    --  Executable_Suffix is specified, add this suffix, otherwise add the
  43    --  standard executable suffix for the platform.
  44    --  What is Ada_Main???
  45    --  What is Language???
  46
  47    procedure Put
  48      (Into_List  : in out Name_List_Index;
  49       From_List  : String_List_Id;
  50       In_Tree    : Project_Tree_Ref;
  51       Lower_Case : Boolean := False);
  52    --  Append a name list to a string list
  53    --  Describe parameters???
  54
  55    procedure Duplicate
  56      (This    : in out Name_List_Index;
  57       In_Tree : Project_Tree_Ref);
  58    --  Duplicate a name list
  59
  60    function Value_Of
  61      (Variable : Variable_Value;
  62       Default  : String) return String;
  63    --  Get the value of a single string variable. If Variable is
  64    --  Nil_Variable_Value, is a string list or is defaulted, return Default.
  65
  66    function Value_Of
  67      (Index    : Name_Id;
  68       In_Array : Array_Element_Id;
  69       In_Tree  : Project_Tree_Ref) return Name_Id;
  70    --  Get a single string array component. Returns No_Name if there is no
  71    --  component Index, if In_Array is null, or if the component is a String
  72    --  list. Depending on the attribute (only attributes may be associative
  73    --  arrays) the index may or may not be case sensitive. If the index is not
  74    --  case sensitive, it is first set to lower case before the search in the
  75    --  associative array.
  76
  77    function Value_Of
  78      (Index                  : Name_Id;
  79       Src_Index              : Int := 0;
  80       In_Array               : Array_Element_Id;
  81       In_Tree                : Project_Tree_Ref;
  82       Force_Lower_Case_Index : Boolean := False) return Variable_Value;
  83    --  Get a string array component (single String or String list). Returns
  84    --  Nil_Variable_Value if no component Index or if In_Array is null.
  85    --
  86    --  Depending on the attribute (only attributes may be associative arrays)
  87    --  the index may or may not be case sensitive. If the index is not case
  88    --  sensitive, it is first set to lower case before the search in the
  89    --  associative array.
  90
  91    function Value_Of
  92      (Name                    : Name_Id;
  93       Index                   : Int := 0;
  94       Attribute_Or_Array_Name : Name_Id;
  95       In_Package              : Package_Id;
  96       In_Tree                 : Project_Tree_Ref;
  97       Force_Lower_Case_Index  : Boolean := False) return Variable_Value;
  98    --  In a specific package,
  99    --   - if there exists an array Attribute_Or_Array_Name with an index Name,
 100    --     returns the corresponding component (depending on the attribute, the
 101    --     index may or may not be case sensitive, see previous function),
 102    --   - otherwise if there is a single attribute Attribute_Or_Array_Name,
 103    --     returns this attribute,
 104    --   - otherwise, returns Nil_Variable_Value.
 105    --  If In_Package is null, returns Nil_Variable_Value.
 106
 107    function Value_Of
 108      (Index     : Name_Id;
 109       In_Array  : Name_Id;
 110       In_Arrays : Array_Id;
 111       In_Tree   : Project_Tree_Ref) return Name_Id;
 112    --  Get a string array component in an array of an array list. Returns
 113    --  No_Name if there is no component Index, if In_Arrays is null, if
 114    --  In_Array is not found in In_Arrays or if the component is a String list.
 115
 116    function Value_Of
 117      (Name      : Name_Id;
 118       In_Arrays : Array_Id;
 119       In_Tree   : Project_Tree_Ref) return Array_Element_Id;
 120    --  Returns a specified array in an array list. Returns No_Array_Element
 121    --  if In_Arrays is null or if Name is not the name of an array in
 122    --  In_Arrays. The caller must ensure that Name is in lower case.
 123
 124    function Value_Of
 125      (Name        : Name_Id;
 126       In_Packages : Package_Id;
 127       In_Tree     : Project_Tree_Ref) return Package_Id;
 128    --  Returns a specified package in a package list. Returns No_Package if
 129    --  In_Packages is null or if Name is not the name of a package in
 130    --  Package_List. The caller must ensure that Name is in lower case.
 131
 132    function Value_Of
 133      (Variable_Name : Name_Id;
 134       In_Variables  : Variable_Id;
 135       In_Tree       : Project_Tree_Ref) return Variable_Value;
 136    --  Returns a specified variable in a variable list. Returns null if
 137    --  In_Variables is null or if Variable_Name is not the name of a
 138    --  variable in In_Variables. Caller must ensure that Name is lower case.
 139
 140    procedure Write_Str
 141      (S          : String;
 142       Max_Length : Positive;
 143       Separator  : Character);
 144    --  Output string S using Output.Write_Str. If S is too long to fit in
 145    --  one line of Max_Length, cut it in several lines, using Separator as
 146    --  the last character of each line, if possible.
 147
 148    type Text_File is limited private;
 149    --  Represents a text file. Default is invalid text file
 150
 151    function Is_Valid (File : Text_File) return Boolean;
 152    --  Returns True if File designates an open text file that
 153    --  has not yet been closed.
 154
 155    procedure Open (File : out Text_File; Name : String);
 156    --  Open a text file. If this procedure fails, File is invalid
 157
 158    function End_Of_File (File : Text_File) return Boolean;
 159    --  Returns True if the end of the text file File has been reached. Fails if
 160    --  File is invalid.
 161
 162    procedure Get_Line
 163      (File : Text_File;
 164       Line : out String;
 165       Last : out Natural);
 166    --  Reads a line from an open text file. Fails if File is invalid
 167
 168    procedure Close (File : in out Text_File);
 169    --  Close an open text file. File becomes invalid. Fails if File is already
 170    --  invalid.
 171
 172 private
 173
 174    type Text_File_Data is record
 175       FD                  : File_Descriptor := Invalid_FD;
 176       Buffer              : String (1 .. 1_000);
 177       Buffer_Len          : Natural;
 178       Cursor              : Natural := 0;
 179       End_Of_File_Reached : Boolean := False;
 180    end record;
 181
 182    type Text_File is access Text_File_Data;
 183
 184 end Prj.Util;