File : 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-2013, 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 -- --
19 -- --
20 -- --
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 pragma Compiler_Unit_Warning;
40
41 with System.Strings;
42
43 package Ada.Command_Line.Response_File is
44
45 subtype String_Access is System.Strings.String_Access;
46 -- type String_Access is access all String;
47
48 procedure Free (S : in out String_Access) renames System.Strings.Free;
49 -- To deallocate a String
50
51 subtype Argument_List is System.Strings.String_List;
52 -- type String_List is array (Positive range <>) of String_Access;
53
54 Max_Line_Length : constant := 4096;
55 -- The maximum length of lines in a response file
56
57 File_Does_Not_Exist : exception;
58 -- Raise by Arguments_From when a response file cannot be found
59
60 Line_Too_Long : exception;
61 -- Raise by Arguments_From when a line in the response file is longer than
62 -- Max_Line_Length.
63
64 No_Closing_Quote : exception;
65 -- Raise by Arguments_From when a quoted string does not end before the
66 -- end of the line.
67
68 Circularity_Detected : exception;
69 -- Raise by Arguments_From when Recursive is True and the same response
70 -- file is reading itself, either directly or indirectly.
71
72 function Arguments_From
73 (Response_File_Name : String;
74 Recursive : Boolean := False;
75 Ignore_Non_Existing_Files : Boolean := False)
76 return Argument_List;
77 -- Read response file with name Response_File_Name and return the argument
78 -- it contains as an Argument_List. It is the responsibility of the caller
79 -- to deallocate the strings in the Argument_List if desired. When
80 -- Recursive is True, any argument of the form @file_name indicates the
81 -- name of another response file and is replaced by the arguments in this
82 -- response file.
83 --
84 -- Each non empty line of the response file contains one or several
85 -- arguments separated by white space. Empty lines or lines containing only
86 -- white space are ignored. Arguments containing white space or a double
87 -- quote ('"')must be quoted. A double quote inside a quote string is
88 -- indicated by two consecutive double quotes. Example: "-Idir with quote
89 -- "" and spaces" Non white space characters immediately before or after a
90 -- quoted string are part of the same argument. Example -Idir" with "spaces
91 --
92 -- When a response file cannot be found, exception File_Does_Not_Exist is
93 -- raised if Ignore_Non_Existing_Files is False, otherwise the response
94 -- file is ignored. Exception Line_Too_Long is raised when a line of a
95 -- response file is longer than Max_Line_Length. Exception No_Closing_Quote
96 -- is raised when a quoted argument is not closed before the end of the
97 -- line. Exception Circularity_Detected is raised when a Recursive is True
98 -- and a response file is reading itself, either directly or indirectly.
99
100 end Ada.Command_Line.Response_File;