1 ------------------------------------------------------------------------------
3 -- GNAT COMPILER COMPONENTS --
5 -- G N A T . C O M M A N D _ L I N E --
10 -- Copyright (C) 1999-2002 Ada Core Technologies, Inc. --
12 -- GNAT is free software; you can redistribute it and/or modify it under --
13 -- terms of the GNU General Public License as published by the Free Soft- --
14 -- ware Foundation; either version 2, or (at your option) any later ver- --
15 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
16 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
17 -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
18 -- for more details. You should have received a copy of the GNU General --
19 -- Public License distributed with GNAT; see file COPYING. If not, write --
20 -- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, --
21 -- MA 02111-1307, USA. --
23 -- As a special exception, if other files instantiate generics from this --
24 -- unit, or you link this unit with other files to produce an executable, --
25 -- this unit does not by itself cause the resulting executable to be --
26 -- covered by the GNU General Public License. This exception does not --
27 -- however invalidate any other reasons why the executable file might be --
28 -- covered by the GNU Public License. --
30 -- GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com). --
32 ------------------------------------------------------------------------------
34 -- High level package for command line parsing
36 -- This package provides an interface to Ada.Command_Line, to do the
37 -- parsing of command line arguments. Here is a small usage example:
41 -- case Getopt ("a b: ad") is -- Accepts '-a', '-ad', or '-b argument'
42 -- when ASCII.NUL => exit;
45 -- if Full_Switch = "a" then
46 -- Put_Line ("Got a");
48 -- Put_Line ("Got ad");
52 -- Put_Line ("Got b + " & Parameter);
55 -- raise Program_Error; -- cannot occur!
61 -- S : constant String := Get_Argument (Do_Expansion => True);
63 -- exit when S'Length = 0;
64 -- Put_Line ("Got " & S);
69 -- when Invalid_Switch => Put_Line ("Invalid Switch " & Full_Switch);
70 -- when Invalid_Parameter => Put_Line ("No parameter for " & Full_Switch);
73 -- A more complicated example would involve the use of sections for the
74 -- switches, as for instance in gnatmake. These sections are separated by
75 -- special switches, chosen by the programer. Each section act as a
76 -- command line of its own.
79 -- Initialize_Option_Scan ('-', False, "largs bargs cargs");
81 -- -- Same loop as above to get switches and arguments
84 -- Goto_Section ("bargs");
86 -- -- Same loop as above to get switches and arguments
87 -- -- The supports switches in Get_Opt might be different
90 -- Goto_Section ("cargs");
92 -- -- Same loop as above to get switches and arguments
93 -- -- The supports switches in Get_Opt might be different
97 with GNAT
.Directory_Operations
;
100 package GNAT
.Command_Line
is
102 procedure Initialize_Option_Scan
103 (Switch_Char
: Character := '-';
104 Stop_At_First_Non_Switch
: Boolean := False;
105 Section_Delimiters
: String := "");
106 -- This procedure resets the internal state of the package to prepare
107 -- to rescan the parameters. It need not (but may be) called before the
108 -- first use of Getopt, but it must be called if you want to start
109 -- rescanning the command line parameters from the start. The optional
110 -- parameter Switch_Char can be used to reset the switch character,
111 -- e.g. to '/' for use in DOS-like systems. The optional parameter
112 -- Stop_At_First_Non_Switch indicates if Getopt is to look for switches
113 -- on the whole command line, or if it has to stop as soon as a
114 -- non-switch argument is found.
118 -- Arguments: my_application file1 -c
120 -- if Stop_At_First_Non_Switch is False, then -c will be considered
121 -- as a switch (returned by getopt), otherwise it will be considered
122 -- as a normal argument (returned by Get_Argument).
124 -- if SECTION_DELIMITERS is set, then every following subprogram
125 -- (Getopt and Get_Argument) will only operate within a section, which
126 -- is delimited by any of these delimiters or the end of the command line.
129 -- Initialize_Option_Scan ("largs bargs cargs");
131 -- Arguments on command line : my_application -c -bargs -d -e -largs -f
132 -- This line is made of three section, the first one is the default one
133 -- and includes only the '-c' switch, the second one is between -bargs
134 -- and -largs and includes '-d -e' and the last one includes '-f'
136 procedure Goto_Section
(Name
: String := "");
137 -- Change the current section. The next Getopt of Get_Argument will
138 -- start looking at the beginning of the section. An empty name ("")
139 -- refers to the first section between the program name and the first
140 -- section delimiter.
141 -- If the section does not exist, then Invalid_Section is raised.
143 function Full_Switch
return String;
144 -- Returns the full name of the last switch found (Getopt only returns
145 -- the first character)
147 function Getopt
(Switches
: String) return Character;
148 -- This function moves to the next switch on the command line (defined
149 -- as a switch character followed by a character within Switches,
150 -- casing being significant). The result returned is the first
151 -- character of the particular switch located. If there are no more
152 -- switches in the current section, returns ASCII.NUL. The switches
153 -- need not be separated by spaces (they can be concatenated if they do
154 -- not require an argument, e.g. -ab is the same as two separate
157 -- Switches is a string of all the possible switches, separated by a
158 -- space. A switch can be followed by one of the following characters :
160 -- ':' The switch requires a parameter. There can optionally be a space
161 -- on the command line between the switch and its parameter
162 -- '=' The switch requires a parameter. There can either be a '=' or a
163 -- space on the command line between the switch and its parameter
164 -- '!' The switch requires a parameter, but there can be no space on the
165 -- command line between the switch and its parameter
166 -- '?' The switch may have an optional parameter. There can no space
167 -- between the switch and its argument
168 -- ex/ if Switches has the following value : "a? b"
169 -- The command line can be :
170 -- -afoo : -a switch with 'foo' parameter
171 -- -a foo : -a switch and another element on the
172 -- command line 'foo', returned by Get_Argument
174 -- Example: if Switches is "-a: -aO:", you can have the following
176 -- -aarg : 'a' switch with 'arg' parameter
177 -- -a arg : 'a' switch with 'arg' parameter
178 -- -aOarg : 'aO' switch with 'arg' parameter
179 -- -aO arg : 'aO' switch with 'arg' parameter
183 -- Getopt ("a b: ac ad?")
185 -- accept either 'a' or 'ac' with no argument,
186 -- accept 'b' with a required argument
187 -- accept 'ad' with an optional argument
189 -- If the first item in switches is '*', then Getopt will catch
190 -- every element on the command line that was not caught by any other
191 -- switch. The character returned by GetOpt is '*'
195 -- If the command line is '-a -c toto.o -b', GetOpt will return
196 -- successively 'a', '*', '*' and 'b'. When '*' is returnd,
197 -- Full_Switch returns the corresponding item on the command line.
200 -- When Getopt encounters an invalid switch, it raises the exception
201 -- Invalid_Switch and sets Full_Switch to return the invalid switch.
202 -- When Getopt can not find the parameter associated with a switch, it
203 -- raises Invalid_Parameter, and sets Full_Switch to return the invalid
206 -- Note: in case of ambiguity, e.g. switches a ab abc, then the longest
207 -- matching switch is returned.
209 -- Arbitrary characters are allowed for switches, although it is
210 -- strongly recommanded to use only letters and digits for portability
213 function Get_Argument
(Do_Expansion
: Boolean := False) return String;
214 -- Returns the next element in the command line which is not a switch.
215 -- This function should not be called before Getopt has returned
218 -- If Expansion is True, then the parameter on the command
219 -- line will considered as filename with wild cards, and will be
220 -- expanded. The matching file names will be returned one at a time.
221 -- When there are no more arguments on the command line, this function
222 -- returns an empty string. This is useful in non-Unix systems for
223 -- obtaining normal expansion of wild card references.
225 function Parameter
return String;
226 -- Returns parameter associated with the last switch returned by Getopt.
227 -- If no parameter was associated with the last switch, or no previous
228 -- call has been made to Get_Argument, raises Invalid_Parameter.
229 -- If the last switch was associated with an optional argument and this
230 -- argument was not found on the command line, Parameter returns an empty
233 type Expansion_Iterator
is limited private;
234 -- Type used during expansion of file names
236 procedure Start_Expansion
237 (Iterator
: out Expansion_Iterator
;
239 Directory
: String := "";
240 Basic_Regexp
: Boolean := True);
241 -- Initialize a wild card expansion. The next calls to Expansion will
242 -- return the next file name in Directory which match Pattern (Pattern
243 -- is a regular expression, using only the Unix shell and DOS syntax if
244 -- Basic_Regexp is True). When Directory is an empty string, the current
245 -- directory is searched.
247 -- Pattern may contains directory separators (as in "src/*/*.ada").
248 -- Subdirectories of Directory will also be searched, up to one
249 -- hundred levels deep.
251 -- When Start_Expansion has been called, function Expansion should be
252 -- called repetitively until it returns an empty string, before
253 -- Start_Expansion can be called again with the same Expansion_Iterator
256 function Expansion
(Iterator
: Expansion_Iterator
) return String;
257 -- Return the next file in the directory matching the parameters given
258 -- to Start_Expansion and updates Iterator to point to the next entry.
259 -- Returns an empty string when there are no more files in the directory
260 -- and its subdirectories.
262 -- If Expansion is called again after an empty string has been returned,
263 -- then the exception GNAT.Directory_Operations.Directory_Error is raised.
265 Invalid_Section
: exception;
266 -- Raised when an invalid section is selected by Goto_Section
268 Invalid_Switch
: exception;
269 -- Raised when an invalid switch is detected in the command line
271 Invalid_Parameter
: exception;
272 -- Raised when a parameter is missing, or an attempt is made to obtain
273 -- a parameter for a switch that does not allow a parameter
277 Max_Depth
: constant := 100;
278 -- Maximum depth of subdirectories
280 Max_Path_Length
: constant := 1024;
281 -- Maximum length of relative path
283 type Depth
is range 1 .. Max_Depth
;
286 Name_Last
: Natural := 0;
287 Dir
: GNAT
.Directory_Operations
.Dir_Type
;
290 type Level_Array
is array (Depth
) of Level
;
292 type Expansion_Iterator
is limited record
293 Start
: Positive := 1;
294 -- Position of the first character of the relative path to check
295 -- against the pattern.
297 Dir_Name
: String (1 .. Max_Path_Length
);
299 Current_Depth
: Depth
:= 1;
301 Levels
: Level_Array
;
303 Regexp
: GNAT
.Regexp
.Regexp
;
304 -- Regular expression built with the pattern
306 Maximum_Depth
: Depth
:= 1;
307 -- The maximum depth of directories, reflecting the number of
308 -- directory separators in the pattern.
312 end GNAT
.Command_Line
;