gcc/ada/a-clrefi.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT RUN-TIME COMPONENTS                         --
   4 --                                                                          --
   5 --       A D A . C O M M A N D _ L I N E . R E S P O N S E _ F I L E        --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --          Copyright (C) 2007-2009, 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.                                     --
  17 --                                                                          --
  18 -- As a special exception under Section 7 of GPL version 3, you are granted --
  19 -- additional permissions described in the GCC Runtime Library Exception,   --
  20 -- version 3.1, as published by the Free Software Foundation.               --
  21 --                                                                          --
  22 -- You should have received a copy of the GNU General Public License and    --
  23 -- a copy of the GCC Runtime Library Exception along with this program;     --
  24 -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
  25 -- <http://www.gnu.org/licenses/>.                                          --
  26 --                                                                          --
  27 -- GNAT was originally developed  by the GNAT team at  New York University. --
  28 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  29 --                                                                          --
  30 ------------------------------------------------------------------------------
  31
  32 --  This package is intended to be used in conjunction with its parent unit,
  33 --  Ada.Command_Line. It provides facilities for getting command line arguments
  34 --  from a text file, called a "response file".
  35 --
  36 --  Using a response file allow passing a set of arguments to an executable
  37 --  longer than the maximum allowed by the system on the command line.
  38
  39 with System.Strings;
  40
  41 package Ada.Command_Line.Response_File is
  42
  43    subtype String_Access is System.Strings.String_Access;
  44    --  type String_Access is access all String;
  45
  46    procedure Free (S : in out String_Access) renames System.Strings.Free;
  47    --  To deallocate a String
  48
  49    subtype Argument_List is System.Strings.String_List;
  50    --  type String_List is array (Positive range <>) of String_Access;
  51
  52    Max_Line_Length : constant := 4096;
  53    --  The maximum length of lines in a response file
  54
  55    File_Does_Not_Exist : exception;
  56    --  Raise by Arguments_From when a response file cannot be found
  57
  58    Line_Too_Long : exception;
  59    --  Raise by Arguments_From when a line in the response file is longer than
  60    --  Max_Line_Length.
  61
  62    No_Closing_Quote : exception;
  63    --  Raise by Arguments_From when a quoted string does not end before the
  64    --  end of the line.
  65
  66    Circularity_Detected : exception;
  67    --  Raise by Arguments_From when Recursive is True and the same response
  68    --  file is reading itself, either directly or indirectly.
  69
  70    function Arguments_From
  71      (Response_File_Name        : String;
  72       Recursive                 : Boolean := False;
  73       Ignore_Non_Existing_Files : Boolean := False)
  74       return Argument_List;
  75    --  Read response file with name Response_File_Name and return the argument
  76    --  it contains as an Argument_List. It is the responsibility of the caller
  77    --  to deallocate the strings in the Argument_List if desired. When
  78    --  Recursive is True, any argument of the form @file_name indicates the
  79    --  name of another response file and is replaced by the arguments in this
  80    --  response file.
  81    --
  82    --  Each non empty line of the response file contains one or several
  83    --  arguments separated by white space. Empty lines or lines containing only
  84    --  white space are ignored. Arguments containing white space or a double
  85    --  quote ('"')must be quoted. A double quote inside a quote string is
  86    --  indicated by two consecutive double quotes. Example: "-Idir with quote
  87    --  "" and spaces" Non white space characters immediately before or after a
  88    --  quoted string are part of the same argument. Example -Idir" with "spaces
  89    --
  90    --  When a response file cannot be found, exception File_Does_Not_Exist is
  91    --  raised if Ignore_Non_Existing_Files is False, otherwise the response
  92    --  file is ignored. Exception Line_Too_Long is raised when a line of a
  93    --  response file is longer than Max_Line_Length. Exception No_Closing_Quote
  94    --  is raised when a quoted argument is not closed before the end of the
  95    --  line. Exception Circularity_Detected is raised when a Recursive is True
  96    --  and a response file is reading itself, either directly or indirectly.
  97
  98 end Ada.Command_Line.Response_File;