1------------------------------------------------------------------------------
2--                                                                          --
3--                         GNAT RUN-TIME COMPONENTS                         --
4--                                                                          --
5--                  S Y S T E M . R E S P O N S E _ F I L E                 --
6--                                                                          --
7--                                 S p e c                                  --
8--                                                                          --
9--          Copyright (C) 2007-2018, 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 provides facilities for getting command-line arguments from
33--  a text file, called a "response file".
34--
35--  Using a response file allow passing a set of arguments to an executable
36--  longer than the maximum allowed by the system on the command line.
37
38pragma Compiler_Unit_Warning;
39
40with System.Strings;
41
42package System.Response_File is
43
44   subtype String_Access is System.Strings.String_Access;
45   --  type String_Access is access all String;
46
47   procedure Free (S : in out String_Access) renames System.Strings.Free;
48   --  To deallocate a String
49
50   subtype Argument_List is System.Strings.String_List;
51   --  type String_List is array (Positive range <>) of String_Access;
52
53   Max_Line_Length : constant := 4096;
54   --  The maximum length of lines in a response file
55
56   File_Does_Not_Exist : exception;
57   --  Raise by Arguments_From when a response file cannot be found
58
59   Line_Too_Long : exception;
60   --  Raise by Arguments_From when a line in the response file is longer than
61   --  Max_Line_Length.
62
63   No_Closing_Quote : exception;
64   --  Raise by Arguments_From when a quoted string does not end before the
65   --  end of the line.
66
67   Circularity_Detected : exception;
68   --  Raise by Arguments_From when Recursive is True and the same response
69   --  file is reading itself, either directly or indirectly.
70
71   function Arguments_From
72     (Response_File_Name        : String;
73      Recursive                 : Boolean := False;
74      Ignore_Non_Existing_Files : Boolean := False)
75      return Argument_List;
76   --  Read response file with name Response_File_Name and return the argument
77   --  it contains as an Argument_List. It is the responsibility of the caller
78   --  to deallocate the strings in the Argument_List if desired. When
79   --  Recursive is True, any argument of the form @file_name indicates the
80   --  name of another response file and is replaced by the arguments in this
81   --  response file.
82   --
83   --  Each nonempty line of the response file contains one or several
84   --  arguments separated by white space. Empty lines or lines containing only
85   --  white space are ignored. Arguments containing white space or a double
86   --  quote ('"')must be quoted. A double quote inside a quote string is
87   --  indicated by two consecutive double quotes. Example: "-Idir with quote
88   --  "" and spaces". Non-white-space characters immediately before or after a
89   --  quoted string are part of the same argument. Ex: -Idir" with "spaces
90   --
91   --  When a response file cannot be found, exception File_Does_Not_Exist is
92   --  raised if Ignore_Non_Existing_Files is False, otherwise the response
93   --  file is ignored. Exception Line_Too_Long is raised when a line of a
94   --  response file is longer than Max_Line_Length. Exception No_Closing_Quote
95   --  is raised when a quoted argument is not closed before the end of the
96   --  line. Exception Circularity_Detected is raised when a Recursive is True
97   --  and a response file is reading itself, either directly or indirectly.
98
99end System.Response_File;
100