|
111
|
1 ------------------------------------------------------------------------------
|
|
|
2 -- --
|
|
|
3 -- GNAT COMPILER COMPONENTS --
|
|
|
4 -- --
|
|
|
5 -- G N A T . C O M M A N D _ L I N E --
|
|
|
6 -- --
|
|
|
7 -- S p e c --
|
|
|
8 -- --
|
|
131
|
9 -- Copyright (C) 1999-2018, AdaCore --
|
|
111
|
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 -- High level package for command line parsing and manipulation
|
|
|
33
|
|
|
34 ----------------------------------------
|
|
|
35 -- Simple Parsing of the Command Line --
|
|
|
36 ----------------------------------------
|
|
|
37
|
|
|
38 -- This package provides an interface for parsing command line arguments,
|
|
|
39 -- when they are either read from Ada.Command_Line or read from a string list.
|
|
|
40 -- As shown in the example below, one should first retrieve the switches
|
|
|
41 -- (special command line arguments starting with '-' by default) and their
|
|
|
42 -- parameters, and then the rest of the command line arguments.
|
|
|
43 --
|
|
|
44 -- While it may appear easy to parse the command line arguments with
|
|
|
45 -- Ada.Command_Line, there are in fact lots of special cases to handle in some
|
|
|
46 -- applications. Those are fully managed by GNAT.Command_Line. Among these are
|
|
|
47 -- switches with optional parameters, grouping switches (for instance "-ab"
|
|
|
48 -- might mean the same as "-a -b"), various characters to separate a switch
|
|
|
49 -- and its parameter (or none: "-a 1" and "-a1" are generally the same, which
|
|
|
50 -- can introduce confusion with grouped switches),...
|
|
|
51 --
|
|
|
52 -- begin
|
|
|
53 -- loop
|
|
|
54 -- case Getopt ("a b: ad") is -- Accepts '-a', '-ad', or '-b argument'
|
|
|
55 -- when ASCII.NUL => exit;
|
|
|
56
|
|
|
57 -- when 'a' =>
|
|
|
58 -- if Full_Switch = "a" then
|
|
|
59 -- Put_Line ("Got a");
|
|
|
60 -- else
|
|
|
61 -- Put_Line ("Got ad");
|
|
|
62 -- end if;
|
|
|
63
|
|
|
64 -- when 'b' => Put_Line ("Got b + " & Parameter);
|
|
|
65
|
|
|
66 -- when others =>
|
|
|
67 -- raise Program_Error; -- cannot occur
|
|
|
68 -- end case;
|
|
|
69 -- end loop;
|
|
|
70
|
|
|
71 -- loop
|
|
|
72 -- declare
|
|
|
73 -- S : constant String := Get_Argument (Do_Expansion => True);
|
|
|
74 -- begin
|
|
|
75 -- exit when S'Length = 0;
|
|
|
76 -- Put_Line ("Got " & S);
|
|
|
77 -- end;
|
|
|
78 -- end loop;
|
|
|
79
|
|
|
80 -- exception
|
|
|
81 -- when Invalid_Switch => Put_Line ("Invalid Switch " & Full_Switch);
|
|
|
82 -- when Invalid_Parameter => Put_Line ("No parameter for " & Full_Switch);
|
|
|
83 -- end;
|
|
|
84
|
|
|
85 --------------
|
|
|
86 -- Sections --
|
|
|
87 --------------
|
|
|
88
|
|
|
89 -- A more complicated example would involve the use of sections for the
|
|
|
90 -- switches, as for instance in gnatmake. The same command line is used to
|
|
|
91 -- provide switches for several tools. Each tool recognizes its switches by
|
|
|
92 -- separating them with special switches that act as section separators.
|
|
|
93 -- Each section acts as a command line of its own.
|
|
|
94
|
|
|
95 -- begin
|
|
|
96 -- Initialize_Option_Scan ('-', False, "largs bargs cargs");
|
|
|
97 -- loop
|
|
|
98 -- -- Same loop as above to get switches and arguments
|
|
|
99 -- end loop;
|
|
|
100
|
|
|
101 -- Goto_Section ("bargs");
|
|
|
102 -- loop
|
|
|
103 -- -- Same loop as above to get switches and arguments
|
|
|
104 -- -- The supported switches in Getopt might be different
|
|
|
105 -- end loop;
|
|
|
106
|
|
|
107 -- Goto_Section ("cargs");
|
|
|
108 -- loop
|
|
|
109 -- -- Same loop as above to get switches and arguments
|
|
|
110 -- -- The supported switches in Getopt might be different
|
|
|
111 -- end loop;
|
|
|
112 -- end;
|
|
|
113
|
|
|
114 -------------------------------
|
|
|
115 -- Parsing a List of Strings --
|
|
|
116 -------------------------------
|
|
|
117
|
|
|
118 -- The examples above show how to parse the command line when the arguments
|
|
|
119 -- are read directly from Ada.Command_Line. However, these arguments can also
|
|
|
120 -- be read from a list of strings. This can be useful in several contexts,
|
|
|
121 -- either because your system does not support Ada.Command_Line, or because
|
|
|
122 -- you are manipulating other tools and creating their command lines by hand,
|
|
|
123 -- or for any other reason.
|
|
|
124
|
|
|
125 -- To create the list of strings, it is recommended to use
|
|
|
126 -- GNAT.OS_Lib.Argument_String_To_List.
|
|
|
127
|
|
|
128 -- The example below shows how to get the parameters from such a list. Note
|
|
|
129 -- also the use of '*' to get all the switches, and not report errors when an
|
|
|
130 -- unexpected switch was used by the user
|
|
|
131
|
|
|
132 -- declare
|
|
|
133 -- Parser : Opt_Parser;
|
|
|
134 -- Args : constant Argument_List_Access :=
|
|
|
135 -- GNAT.OS_Lib.Argument_String_To_List ("-g -O1 -Ipath");
|
|
|
136 -- begin
|
|
|
137 -- Initialize_Option_Scan (Parser, Args);
|
|
|
138 -- while Getopt ("* g O! I=", Parser) /= ASCII.NUL loop
|
|
|
139 -- Put_Line ("Switch " & Full_Switch (Parser)
|
|
|
140 -- & " param=" & Parameter (Parser));
|
|
|
141 -- end loop;
|
|
|
142 -- Free (Parser);
|
|
|
143 -- end;
|
|
|
144
|
|
|
145 -------------------------------------------
|
|
|
146 -- High-Level Command Line Configuration --
|
|
|
147 -------------------------------------------
|
|
|
148
|
|
|
149 -- As shown above, the code is still relatively low-level. For instance, there
|
|
|
150 -- is no way to indicate which switches are related (thus if "-l" and "--long"
|
|
|
151 -- should have the same effect, your code will need to test for both cases).
|
|
|
152 -- Likewise, it is difficult to handle more advanced constructs, like:
|
|
|
153
|
|
|
154 -- * Specifying -gnatwa is the same as specifying -gnatwu -gnatwv, but
|
|
|
155 -- shorter and more readable
|
|
|
156
|
|
|
157 -- * All switches starting with -gnatw can be grouped, for instance one
|
|
|
158 -- can write -gnatwcd instead of -gnatwc -gnatwd.
|
|
|
159 -- Of course, this can be combined with the above and -gnatwacd is the
|
|
|
160 -- same as -gnatwc -gnatwd -gnatwu -gnatwv
|
|
|
161
|
|
|
162 -- * The switch -T is the same as -gnatwAB (same as -gnatwA -gnatwB)
|
|
|
163
|
|
|
164 -- With the above form of Getopt, you would receive "-gnatwa", "-T" or
|
|
|
165 -- "-gnatwcd" in the examples above, and thus you require additional manual
|
|
|
166 -- parsing of the switch.
|
|
|
167
|
|
|
168 -- Instead, this package provides the type Command_Line_Configuration, which
|
|
|
169 -- stores all the knowledge above. For instance:
|
|
|
170
|
|
|
171 -- Config : Command_Line_Configuration;
|
|
|
172 -- Define_Alias (Config, "-gnatwa", "-gnatwu -gnatwv");
|
|
|
173 -- Define_Prefix (Config, "-gnatw");
|
|
|
174 -- Define_Alias (Config, "-T", "-gnatwAB");
|
|
|
175
|
|
|
176 -- You then need to specify all possible switches in your application by
|
|
|
177 -- calling Define_Switch, for instance:
|
|
|
178
|
|
|
179 -- Define_Switch (Config, "-gnatwu", Help => "warn on unused entities");
|
|
|
180 -- Define_Switch (Config, "-gnatwv", Help => "warn on unassigned var");
|
|
|
181 -- ...
|
|
|
182
|
|
|
183 -- Specifying the help message is optional, but makes it easy to then call
|
|
|
184 -- the function:
|
|
|
185
|
|
|
186 -- Display_Help (Config);
|
|
|
187
|
|
|
188 -- that will display a properly formatted help message for your application,
|
|
|
189 -- listing all possible switches. That way you have a single place in which
|
|
|
190 -- to maintain the list of switches and their meaning, rather than maintaining
|
|
|
191 -- both the string to pass to Getopt and a subprogram to display the help.
|
|
|
192 -- Both will properly stay synchronized.
|
|
|
193
|
|
|
194 -- Once you have this Config, you just have to call:
|
|
|
195
|
|
|
196 -- Getopt (Config, Callback'Access);
|
|
|
197
|
|
|
198 -- to parse the command line. The Callback will be called for each switch
|
|
|
199 -- found on the command line (in the case of our example, that is "-gnatwu"
|
|
|
200 -- and then "-gnatwv", not "-gnatwa" itself). This simplifies command line
|
|
|
201 -- parsing a lot.
|
|
|
202
|
|
|
203 -- In fact, this can be further automated for the most command case where the
|
|
|
204 -- parameter passed to a switch is stored in a variable in the application.
|
|
|
205 -- When a switch is defined, you only have to indicate where to store the
|
|
|
206 -- value, and let Getopt do the rest. For instance:
|
|
|
207
|
|
|
208 -- Optimization : aliased Integer;
|
|
|
209 -- Verbose : aliased Boolean;
|
|
|
210
|
|
|
211 -- Define_Switch (Config, Verbose'Access,
|
|
|
212 -- "-v", Long_Switch => "--verbose",
|
|
|
213 -- Help => "Output extra verbose information");
|
|
|
214 -- Define_Switch (Config, Optimization'Access,
|
|
|
215 -- "-O?", Help => "Optimization level");
|
|
|
216
|
|
|
217 -- Getopt (Config); -- No callback
|
|
|
218
|
|
|
219 -- Since all switches are handled automatically, we don't even need to pass
|
|
|
220 -- a callback to Getopt. Once getopt has been called, the two variables
|
|
|
221 -- Optimization and Verbose have been properly initialized, either to the
|
|
|
222 -- default value or to the value found on the command line.
|
|
|
223
|
|
|
224 ------------------------------------------------
|
|
|
225 -- Creating and Manipulating the Command Line --
|
|
|
226 ------------------------------------------------
|
|
|
227
|
|
|
228 -- This package provides mechanisms to create and modify command lines by
|
|
|
229 -- adding or removing arguments from them. The resulting command line is kept
|
|
|
230 -- as short as possible by coalescing arguments whenever possible.
|
|
|
231
|
|
|
232 -- Complex command lines can thus be constructed, for example from a GUI
|
|
|
233 -- (although this package does not by itself depend upon any specific GUI
|
|
|
234 -- toolkit).
|
|
|
235
|
|
|
236 -- Using the configuration defined earlier, one can then construct a command
|
|
|
237 -- line for the tool with:
|
|
|
238
|
|
|
239 -- Cmd : Command_Line;
|
|
|
240 -- Set_Configuration (Cmd, Config); -- Config created earlier
|
|
|
241 -- Add_Switch (Cmd, "-bar");
|
|
|
242 -- Add_Switch (Cmd, "-gnatwu");
|
|
|
243 -- Add_Switch (Cmd, "-gnatwv"); -- will be grouped with the above
|
|
|
244 -- Add_Switch (Cmd, "-T");
|
|
|
245
|
|
|
246 -- The resulting command line can be iterated over to get all its switches,
|
|
|
247 -- There are two modes for this iteration: either you want to get the
|
|
|
248 -- shortest possible command line, which would be:
|
|
|
249
|
|
|
250 -- -bar -gnatwaAB
|
|
|
251
|
|
|
252 -- or on the other hand you want each individual switch (so that your own
|
|
|
253 -- tool does not have to do further complex processing), which would be:
|
|
|
254
|
|
|
255 -- -bar -gnatwu -gnatwv -gnatwA -gnatwB
|
|
|
256
|
|
|
257 -- Of course, we can assume that the tool you want to spawn would understand
|
|
|
258 -- both of these, since they are both compatible with the description we gave
|
|
|
259 -- above. However, the first result is useful if you want to show the user
|
|
|
260 -- what you are spawning (since that keeps the output shorter), and the second
|
|
|
261 -- output is more useful for a tool that would check whether -gnatwu was
|
|
|
262 -- passed (which isn't obvious in the first output). Likewise, the second
|
|
|
263 -- output is more useful if you have a graphical interface since each switch
|
|
|
264 -- can be associated with a widget, and you immediately know whether -gnatwu
|
|
|
265 -- was selected.
|
|
|
266 --
|
|
|
267 -- Some command line arguments can have parameters, which on a command line
|
|
|
268 -- appear as a separate argument that must immediately follow the switch.
|
|
|
269 -- Since the subprograms in this package will reorganize the switches to group
|
|
|
270 -- them, you need to indicate what is a command line parameter, and what is a
|
|
|
271 -- switch argument.
|
|
|
272
|
|
|
273 -- This is done by passing an extra argument to Add_Switch, as in:
|
|
|
274
|
|
|
275 -- Add_Switch (Cmd, "-foo", Parameter => "arg1");
|
|
|
276
|
|
|
277 -- This ensures that "arg1" will always be treated as the argument to -foo,
|
|
|
278 -- and will not be grouped with other parts of the command line.
|
|
|
279
|
|
|
280 with Ada.Command_Line;
|
|
|
281
|
|
|
282 with GNAT.Directory_Operations;
|
|
|
283 with GNAT.OS_Lib;
|
|
|
284 with GNAT.Regexp;
|
|
|
285 with GNAT.Strings;
|
|
|
286
|
|
|
287 package GNAT.Command_Line is
|
|
|
288
|
|
|
289 -------------
|
|
|
290 -- Parsing --
|
|
|
291 -------------
|
|
|
292
|
|
|
293 type Opt_Parser is private;
|
|
|
294 Command_Line_Parser : constant Opt_Parser;
|
|
|
295 -- This object is responsible for parsing a list of arguments, which by
|
|
|
296 -- default are the standard command line arguments from Ada.Command_Line.
|
|
|
297 -- This is really a pointer to actual data, which must therefore be
|
|
|
298 -- initialized through a call to Initialize_Option_Scan, and must be freed
|
|
|
299 -- with a call to Free.
|
|
|
300 --
|
|
|
301 -- As a special case, Command_Line_Parser does not need to be either
|
|
|
302 -- initialized or free-ed.
|
|
|
303
|
|
|
304 procedure Initialize_Option_Scan
|
|
|
305 (Switch_Char : Character := '-';
|
|
|
306 Stop_At_First_Non_Switch : Boolean := False;
|
|
|
307 Section_Delimiters : String := "");
|
|
|
308 procedure Initialize_Option_Scan
|
|
|
309 (Parser : out Opt_Parser;
|
|
|
310 Command_Line : GNAT.OS_Lib.Argument_List_Access;
|
|
|
311 Switch_Char : Character := '-';
|
|
|
312 Stop_At_First_Non_Switch : Boolean := False;
|
|
|
313 Section_Delimiters : String := "");
|
|
|
314 -- The first procedure resets the internal state of the package to prepare
|
|
|
315 -- to rescan the parameters. It does not need to be called before the
|
|
|
316 -- first use of Getopt (but it could be), but it must be called if you
|
|
|
317 -- want to start rescanning the command line parameters from the start.
|
|
|
318 -- The optional parameter Switch_Char can be used to reset the switch
|
|
|
319 -- character, e.g. to '/' for use in DOS-like systems.
|
|
|
320 --
|
|
|
321 -- The second subprogram initializes a parser that takes its arguments
|
|
|
322 -- from an array of strings rather than directly from the command line. In
|
|
|
323 -- this case, the parser is responsible for freeing the strings stored in
|
|
|
324 -- Command_Line. If you pass null to Command_Line, this will in fact create
|
|
|
325 -- a second parser for Ada.Command_Line, which doesn't share any data with
|
|
|
326 -- the default parser. This parser must be free'ed.
|
|
|
327 --
|
|
|
328 -- The optional parameter Stop_At_First_Non_Switch indicates if Getopt is
|
|
|
329 -- to look for switches on the whole command line, or if it has to stop as
|
|
|
330 -- soon as a non-switch argument is found.
|
|
|
331 --
|
|
|
332 -- Example:
|
|
|
333 --
|
|
|
334 -- Arguments: my_application file1 -c
|
|
|
335 --
|
|
|
336 -- If Stop_At_First_Non_Switch is False, then -c will be considered
|
|
|
337 -- as a switch (returned by getopt), otherwise it will be considered
|
|
|
338 -- as a normal argument (returned by Get_Argument).
|
|
|
339 --
|
|
|
340 -- If Section_Delimiters is set, then every following subprogram
|
|
|
341 -- (Getopt and Get_Argument) will only operate within a section, which
|
|
|
342 -- is delimited by any of these delimiters or the end of the command line.
|
|
|
343 --
|
|
|
344 -- Example:
|
|
|
345 -- Initialize_Option_Scan (Section_Delimiters => "largs bargs cargs");
|
|
|
346 --
|
|
|
347 -- Arguments on command line : my_application -c -bargs -d -e -largs -f
|
|
|
348 -- This line contains three sections, the first one is the default one
|
|
|
349 -- and includes only the '-c' switch, the second one is between -bargs
|
|
|
350 -- and -largs and includes '-d -e' and the last one includes '-f'.
|
|
|
351
|
|
|
352 procedure Free (Parser : in out Opt_Parser);
|
|
|
353 -- Free the memory used by the parser. Calling this is not mandatory for
|
|
|
354 -- the Command_Line_Parser
|
|
|
355
|
|
|
356 procedure Goto_Section
|
|
|
357 (Name : String := "";
|
|
|
358 Parser : Opt_Parser := Command_Line_Parser);
|
|
|
359 -- Change the current section. The next Getopt or Get_Argument will start
|
|
|
360 -- looking at the beginning of the section. An empty name ("") refers to
|
|
|
361 -- the first section between the program name and the first section
|
|
|
362 -- delimiter. If the section does not exist in Section_Delimiters, then
|
|
|
363 -- Invalid_Section is raised. If the section does not appear on the command
|
|
|
364 -- line, then it is treated as an empty section.
|
|
|
365
|
|
|
366 function Full_Switch
|
|
|
367 (Parser : Opt_Parser := Command_Line_Parser) return String;
|
|
|
368 -- Returns the full name of the last switch found (Getopt only returns the
|
|
|
369 -- first character). Does not include the Switch_Char ('-' by default),
|
|
|
370 -- unless the "*" option of Getopt is used (see below).
|
|
|
371
|
|
|
372 function Current_Section
|
|
|
373 (Parser : Opt_Parser := Command_Line_Parser) return String;
|
|
|
374 -- Return the name of the current section.
|
|
|
375 -- The list of valid sections is defined through Initialize_Option_Scan
|
|
|
376
|
|
|
377 function Getopt
|
|
|
378 (Switches : String;
|
|
|
379 Concatenate : Boolean := True;
|
|
|
380 Parser : Opt_Parser := Command_Line_Parser) return Character;
|
|
|
381 -- This function moves to the next switch on the command line (defined as
|
|
|
382 -- switch character followed by a character within Switches, casing being
|
|
|
383 -- significant). The result returned is the first character of the switch
|
|
|
384 -- that is located. If there are no more switches in the current section,
|
|
|
385 -- returns ASCII.NUL. If Concatenate is True (the default), the switches do
|
|
|
386 -- not need to be separated by spaces (they can be concatenated if they do
|
|
|
387 -- not require an argument, e.g. -ab is the same as two separate arguments
|
|
|
388 -- -a -b).
|
|
|
389 --
|
|
|
390 -- Switches is a string of all the possible switches, separated by
|
|
|
391 -- spaces. A switch can be followed by one of the following characters:
|
|
|
392 --
|
|
|
393 -- ':' The switch requires a parameter. There can optionally be a space
|
|
|
394 -- on the command line between the switch and its parameter.
|
|
|
395 --
|
|
|
396 -- '=' The switch requires a parameter. There can either be a '=' or a
|
|
|
397 -- space on the command line between the switch and its parameter.
|
|
|
398 --
|
|
|
399 -- '!' The switch requires a parameter, but there can be no space on the
|
|
|
400 -- command line between the switch and its parameter.
|
|
|
401 --
|
|
|
402 -- '?' The switch may have an optional parameter. There can be no space
|
|
|
403 -- between the switch and its argument.
|
|
|
404 --
|
|
|
405 -- e.g. if Switches has the following value : "a? b",
|
|
|
406 -- The command line can be:
|
|
|
407 --
|
|
|
408 -- -afoo : -a switch with 'foo' parameter
|
|
|
409 -- -a foo : -a switch and another element on the
|
|
|
410 -- command line 'foo', returned by Get_Argument
|
|
|
411 --
|
|
|
412 -- Example: if Switches is "-a: -aO:", you can have the following
|
|
|
413 -- command lines:
|
|
|
414 --
|
|
|
415 -- -aarg : 'a' switch with 'arg' parameter
|
|
|
416 -- -a arg : 'a' switch with 'arg' parameter
|
|
|
417 -- -aOarg : 'aO' switch with 'arg' parameter
|
|
|
418 -- -aO arg : 'aO' switch with 'arg' parameter
|
|
|
419 --
|
|
|
420 -- Example:
|
|
|
421 --
|
|
|
422 -- Getopt ("a b: ac ad?")
|
|
|
423 --
|
|
|
424 -- accept either 'a' or 'ac' with no argument,
|
|
|
425 -- accept 'b' with a required argument
|
|
|
426 -- accept 'ad' with an optional argument
|
|
|
427 --
|
|
|
428 -- If the first item in switches is '*', then Getopt will catch
|
|
|
429 -- every element on the command line that was not caught by any other
|
|
|
430 -- switch. The character returned by GetOpt is '*', but Full_Switch
|
|
|
431 -- contains the full command line argument, including leading '-' if there
|
|
|
432 -- is one. If this character was not returned, there would be no way of
|
|
|
433 -- knowing whether it is there or not.
|
|
|
434 --
|
|
|
435 -- Example
|
|
|
436 -- Getopt ("* a b")
|
|
|
437 -- If the command line is '-a -c toto.o -b', Getopt will return
|
|
|
438 -- successively 'a', '*', '*' and 'b', with Full_Switch returning
|
|
|
439 -- "a", "-c", "toto.o", and "b".
|
|
|
440 --
|
|
|
441 -- When Getopt encounters an invalid switch, it raises the exception
|
|
|
442 -- Invalid_Switch and sets Full_Switch to return the invalid switch.
|
|
|
443 -- When Getopt cannot find the parameter associated with a switch, it
|
|
|
444 -- raises Invalid_Parameter, and sets Full_Switch to return the invalid
|
|
|
445 -- switch.
|
|
|
446 --
|
|
|
447 -- Note: in case of ambiguity, e.g. switches a ab abc, then the longest
|
|
|
448 -- matching switch is returned.
|
|
|
449 --
|
|
|
450 -- Arbitrary characters are allowed for switches, although it is
|
|
|
451 -- strongly recommended to use only letters and digits for portability
|
|
|
452 -- reasons.
|
|
|
453 --
|
|
|
454 -- When Concatenate is False, individual switches need to be separated by
|
|
|
455 -- spaces.
|
|
|
456 --
|
|
|
457 -- Example
|
|
|
458 -- Getopt ("a b", Concatenate => False)
|
|
|
459 -- If the command line is '-ab', exception Invalid_Switch will be
|
|
|
460 -- raised and Full_Switch will return "ab".
|
|
|
461
|
|
|
462 function Get_Argument
|
|
|
463 (Do_Expansion : Boolean := False;
|
|
|
464 Parser : Opt_Parser := Command_Line_Parser) return String;
|
|
|
465 -- Returns the next element on the command line that is not a switch. This
|
|
|
466 -- function should not be called before Getopt has returned ASCII.NUL.
|
|
|
467 --
|
|
|
468 -- If Do_Expansion is True, then the parameter on the command line will
|
|
|
469 -- be considered as a filename with wild cards, and will be expanded. The
|
|
|
470 -- matching file names will be returned one at a time. This is useful in
|
|
|
471 -- non-Unix systems for obtaining normal expansion of wild card references.
|
|
|
472 -- When there are no more arguments on the command line, this function
|
|
|
473 -- returns an empty string.
|
|
|
474
|
|
|
475 function Parameter
|
|
|
476 (Parser : Opt_Parser := Command_Line_Parser) return String;
|
|
|
477 -- Returns parameter associated with the last switch returned by Getopt.
|
|
|
478 -- If no parameter was associated with the last switch, or no previous call
|
|
|
479 -- has been made to Get_Argument, raises Invalid_Parameter. If the last
|
|
|
480 -- switch was associated with an optional argument and this argument was
|
|
|
481 -- not found on the command line, Parameter returns an empty string.
|
|
|
482
|
|
|
483 function Separator
|
|
|
484 (Parser : Opt_Parser := Command_Line_Parser) return Character;
|
|
|
485 -- The separator that was between the switch and its parameter. This is
|
|
|
486 -- useful if you want to know exactly what was on the command line. This
|
|
|
487 -- is in general a single character, set to ASCII.NUL if the switch and
|
|
|
488 -- the parameter were concatenated. A space is returned if the switch and
|
|
|
489 -- its argument were in two separate arguments.
|
|
|
490
|
|
|
491 Invalid_Section : exception;
|
|
|
492 -- Raised when an invalid section is selected by Goto_Section
|
|
|
493
|
|
|
494 Invalid_Switch : exception;
|
|
|
495 -- Raised when an invalid switch is detected in the command line
|
|
|
496
|
|
|
497 Invalid_Parameter : exception;
|
|
|
498 -- Raised when a parameter is missing, or an attempt is made to obtain a
|
|
|
499 -- parameter for a switch that does not allow a parameter.
|
|
|
500
|
|
|
501 -----------------------------------------
|
|
|
502 -- Expansion of command line arguments --
|
|
|
503 -----------------------------------------
|
|
|
504
|
|
|
505 -- These subprograms take care of expanding globbing patterns on the
|
|
|
506 -- command line. On Unix, such expansion is done by the shell before your
|
|
|
507 -- application is called. But on Windows you must do this expansion
|
|
|
508 -- yourself.
|
|
|
509
|
|
|
510 type Expansion_Iterator is limited private;
|
|
|
511 -- Type used during expansion of file names
|
|
|
512
|
|
|
513 procedure Start_Expansion
|
|
|
514 (Iterator : out Expansion_Iterator;
|
|
|
515 Pattern : String;
|
|
|
516 Directory : String := "";
|
|
|
517 Basic_Regexp : Boolean := True);
|
|
|
518 -- Initialize a wild card expansion. The next calls to Expansion will
|
|
|
519 -- return the next file name in Directory which match Pattern (Pattern
|
|
|
520 -- is a regular expression, using only the Unix shell and DOS syntax if
|
|
|
521 -- Basic_Regexp is True). When Directory is an empty string, the current
|
|
|
522 -- directory is searched.
|
|
|
523 --
|
|
|
524 -- Pattern may contain directory separators (as in "src/*/*.ada").
|
|
|
525 -- Subdirectories of Directory will also be searched, up to one
|
|
|
526 -- hundred levels deep.
|
|
|
527 --
|
|
|
528 -- When Start_Expansion has been called, function Expansion should
|
|
|
529 -- be called repeatedly until it returns an empty string, before
|
|
|
530 -- Start_Expansion can be called again with the same Expansion_Iterator
|
|
|
531 -- variable.
|
|
|
532
|
|
|
533 function Expansion (Iterator : Expansion_Iterator) return String;
|
|
|
534 -- Returns the next file in the directory matching the parameters given
|
|
|
535 -- to Start_Expansion and updates Iterator to point to the next entry.
|
|
|
536 -- Returns an empty string when there are no more files.
|
|
|
537 --
|
|
|
538 -- If Expansion is called again after an empty string has been returned,
|
|
|
539 -- then the exception GNAT.Directory_Operations.Directory_Error is raised.
|
|
|
540
|
|
|
541 -----------------
|
|
|
542 -- Configuring --
|
|
|
543 -----------------
|
|
|
544
|
|
|
545 -- The following subprograms are used to manipulate a command line
|
|
|
546 -- represented as a string (for instance "-g -O2"), as well as parsing
|
|
|
547 -- the switches from such a string. They provide high-level configurations
|
|
|
548 -- to define aliases (a switch is equivalent to one or more other switches)
|
|
|
549 -- or grouping of switches ("-gnatyac" is equivalent to "-gnatya" and
|
|
|
550 -- "-gnatyc").
|
|
|
551
|
|
|
552 -- See the top of this file for examples on how to use these subprograms
|
|
|
553
|
|
|
554 type Command_Line_Configuration is private;
|
|
|
555
|
|
|
556 procedure Define_Section
|
|
|
557 (Config : in out Command_Line_Configuration;
|
|
|
558 Section : String);
|
|
|
559 -- Indicates a new switch section. All switches belonging to the same
|
|
|
560 -- section are ordered together, preceded by the section. They are placed
|
|
|
561 -- at the end of the command line (as in "gnatmake somefile.adb -cargs -g")
|
|
|
562 --
|
|
|
563 -- The section name should not include the leading '-'. So for instance in
|
|
|
564 -- the case of gnatmake we would use:
|
|
|
565 --
|
|
|
566 -- Define_Section (Config, "cargs");
|
|
|
567 -- Define_Section (Config, "bargs");
|
|
|
568
|
|
|
569 procedure Define_Alias
|
|
|
570 (Config : in out Command_Line_Configuration;
|
|
|
571 Switch : String;
|
|
|
572 Expanded : String;
|
|
|
573 Section : String := "");
|
|
|
574 -- Indicates that whenever Switch appears on the command line, it should
|
|
|
575 -- be expanded as Expanded. For instance, for the GNAT compiler switches,
|
|
|
576 -- we would define "-gnatwa" as an alias for "-gnatwcfijkmopruvz", ie some
|
|
|
577 -- default warnings to be activated.
|
|
|
578 --
|
|
|
579 -- This expansion is only done within the specified section, which must
|
|
|
580 -- have been defined first through a call to [Define_Section].
|
|
|
581
|
|
|
582 procedure Define_Prefix
|
|
|
583 (Config : in out Command_Line_Configuration;
|
|
|
584 Prefix : String);
|
|
|
585 -- Indicates that all switches starting with the given prefix should be
|
|
|
586 -- grouped. For instance, for the GNAT compiler we would define "-gnatw" as
|
|
|
587 -- a prefix, so that "-gnatwu -gnatwv" can be grouped into "-gnatwuv" It is
|
|
|
588 -- assumed that the remainder of the switch ("uv") is a set of characters
|
|
|
589 -- whose order is irrelevant. In fact, this package will sort them
|
|
|
590 -- alphabetically.
|
|
|
591 --
|
|
|
592 -- When grouping switches that accept arguments (for instance "-gnatyL!"
|
|
|
593 -- as the definition, and "-gnatyaL12b" as the command line), only
|
|
|
594 -- numerical arguments are accepted. The above is equivalent to
|
|
|
595 -- "-gnatya -gnatyL12 -gnatyb".
|
|
|
596
|
|
|
597 procedure Define_Switch
|
|
|
598 (Config : in out Command_Line_Configuration;
|
|
|
599 Switch : String := "";
|
|
|
600 Long_Switch : String := "";
|
|
|
601 Help : String := "";
|
|
|
602 Section : String := "";
|
|
|
603 Argument : String := "ARG");
|
|
|
604 -- Indicates a new switch. The format of this switch follows the getopt
|
|
|
605 -- format (trailing ':', '?', etc for defining a switch with parameters).
|
|
|
606 --
|
|
|
607 -- Switch should also start with the leading '-' (or any other characters).
|
|
|
608 -- If this character is not '-', you need to call Initialize_Option_Scan to
|
|
|
609 -- set the proper character for the parser.
|
|
|
610 --
|
|
|
611 -- The switches defined in the command_line_configuration object are used
|
|
|
612 -- when ungrouping switches with more that one character after the prefix.
|
|
|
613 --
|
|
|
614 -- Switch and Long_Switch (when specified) are aliases and can be used
|
|
|
615 -- interchangeably. There is no check that they both take an argument or
|
|
|
616 -- both take no argument. Switch can be set to "*" to indicate that any
|
|
|
617 -- switch is supported (in which case Getopt will return '*', see its
|
|
|
618 -- documentation).
|
|
|
619 --
|
|
|
620 -- Help is used by the Display_Help procedure to describe the supported
|
|
|
621 -- switches.
|
|
|
622 --
|
|
|
623 -- In_Section indicates in which section the switch is valid (you need to
|
|
|
624 -- first define the section through a call to Define_Section).
|
|
|
625 --
|
|
|
626 -- Argument is the name of the argument, as displayed in the automatic
|
|
|
627 -- help message. It is always capitalized for consistency.
|
|
|
628
|
|
|
629 procedure Define_Switch
|
|
|
630 (Config : in out Command_Line_Configuration;
|
|
|
631 Output : access Boolean;
|
|
|
632 Switch : String := "";
|
|
|
633 Long_Switch : String := "";
|
|
|
634 Help : String := "";
|
|
|
635 Section : String := "";
|
|
|
636 Value : Boolean := True);
|
|
|
637 -- See Define_Switch for a description of the parameters.
|
|
|
638 -- When the switch is found on the command line, Getopt will set
|
|
|
639 -- Output.all to Value.
|
|
|
640 --
|
|
|
641 -- Output is always initially set to "not Value", so that if the switch is
|
|
|
642 -- not found on the command line, Output still has a valid value.
|
|
|
643 -- The switch must not take any parameter.
|
|
|
644 --
|
|
|
645 -- Output must exist at least as long as Config, otherwise an erroneous
|
|
|
646 -- memory access may occur.
|
|
|
647
|
|
|
648 procedure Define_Switch
|
|
|
649 (Config : in out Command_Line_Configuration;
|
|
|
650 Output : access Integer;
|
|
|
651 Switch : String := "";
|
|
|
652 Long_Switch : String := "";
|
|
|
653 Help : String := "";
|
|
|
654 Section : String := "";
|
|
|
655 Initial : Integer := 0;
|
|
|
656 Default : Integer := 1;
|
|
|
657 Argument : String := "ARG");
|
|
|
658 -- See Define_Switch for a description of the parameters. When the
|
|
|
659 -- switch is found on the command line, Getopt will set Output.all to the
|
|
|
660 -- value of the switch's parameter. If the parameter is not an integer,
|
|
|
661 -- Invalid_Parameter is raised.
|
|
|
662
|
|
|
663 -- Output is always initialized to Initial. If the switch has an optional
|
|
|
664 -- argument which isn't specified by the user, then Output will be set to
|
|
|
665 -- Default. The switch must accept an argument.
|
|
|
666
|
|
|
667 procedure Define_Switch
|
|
|
668 (Config : in out Command_Line_Configuration;
|
|
|
669 Output : access GNAT.Strings.String_Access;
|
|
|
670 Switch : String := "";
|
|
|
671 Long_Switch : String := "";
|
|
|
672 Help : String := "";
|
|
|
673 Section : String := "";
|
|
|
674 Argument : String := "ARG");
|
|
|
675 -- Set Output to the value of the switch's parameter when the switch is
|
|
|
676 -- found on the command line. Output is always initialized to the empty
|
|
|
677 -- string if it does not have a value already (otherwise it is left as is
|
|
|
678 -- so that you can specify the default value directly in the declaration
|
|
|
679 -- of the variable). The switch must accept an argument.
|
|
|
680
|
|
131
|
681 type Value_Callback is access procedure (Switch, Value : String);
|
|
|
682
|
|
|
683 procedure Define_Switch
|
|
|
684 (Config : in out Command_Line_Configuration;
|
|
|
685 Callback : not null Value_Callback;
|
|
|
686 Switch : String := "";
|
|
|
687 Long_Switch : String := "";
|
|
|
688 Help : String := "";
|
|
|
689 Section : String := "";
|
|
|
690 Argument : String := "ARG");
|
|
|
691 -- Call Callback for each instance of Switch. The callback is given the
|
|
|
692 -- actual switch and the corresponding value. The switch must accept
|
|
|
693 -- an argument.
|
|
|
694
|
|
111
|
695 procedure Set_Usage
|
|
|
696 (Config : in out Command_Line_Configuration;
|
|
|
697 Usage : String := "[switches] [arguments]";
|
|
|
698 Help : String := "";
|
|
|
699 Help_Msg : String := "");
|
|
|
700 -- Defines the general format of the call to the application, and a short
|
|
|
701 -- help text. These are both displayed by Display_Help. When a non-empty
|
|
|
702 -- Help_Msg is given, it is used by Display_Help instead of the
|
|
|
703 -- automatically generated list of supported switches.
|
|
|
704
|
|
|
705 procedure Display_Help (Config : Command_Line_Configuration);
|
|
131
|
706 -- Display the help for the tool (i.e. its usage, and its supported
|
|
|
707 -- switches).
|
|
111
|
708
|
|
|
709 function Get_Switches
|
|
|
710 (Config : Command_Line_Configuration;
|
|
|
711 Switch_Char : Character := '-';
|
|
|
712 Section : String := "") return String;
|
|
|
713 -- Get the switches list as expected by Getopt, for a specific section of
|
|
|
714 -- the command line. This list is built using all switches defined
|
|
|
715 -- previously via Define_Switch above.
|
|
|
716
|
|
|
717 function Section_Delimiters
|
|
|
718 (Config : Command_Line_Configuration) return String;
|
|
|
719 -- Return a string suitable for use in Initialize_Option_Scan
|
|
|
720
|
|
|
721 procedure Free (Config : in out Command_Line_Configuration);
|
|
|
722 -- Free the memory used by Config
|
|
|
723
|
|
|
724 type Switch_Handler is access procedure
|
|
|
725 (Switch : String;
|
|
|
726 Parameter : String;
|
|
|
727 Section : String);
|
|
|
728 -- Called when a switch is found on the command line. Switch includes
|
|
|
729 -- any leading '-' that was specified in Define_Switch. This is slightly
|
|
|
730 -- different from the functional version of Getopt above, for which
|
|
|
731 -- Full_Switch omits the first leading '-'.
|
|
|
732
|
|
|
733 Exit_From_Command_Line : exception;
|
|
|
734 -- Emitted when the program should exit. This is called when Getopt below
|
|
|
735 -- has seen -h, --help or an invalid switch.
|
|
|
736
|
|
|
737 procedure Getopt
|
|
|
738 (Config : Command_Line_Configuration;
|
|
|
739 Callback : Switch_Handler := null;
|
|
|
740 Parser : Opt_Parser := Command_Line_Parser;
|
|
|
741 Concatenate : Boolean := True);
|
|
|
742 -- Similar to the standard Getopt function. For each switch found on the
|
|
|
743 -- command line, this calls Callback, if the switch is not handled
|
|
|
744 -- automatically.
|
|
|
745 --
|
|
|
746 -- The list of valid switches are the ones from the configuration. The
|
|
|
747 -- switches that were declared through Define_Switch with an Output
|
|
|
748 -- parameter are never returned (and result in a modification of the Output
|
|
|
749 -- variable). This function will in fact never call [Callback] if all
|
|
|
750 -- switches were handled automatically and there is nothing left to do.
|
|
|
751 --
|
|
|
752 -- The option Concatenate is identical to the one of the standard Getopt
|
|
|
753 -- function.
|
|
|
754 --
|
|
|
755 -- This procedure automatically adds -h and --help to the valid switches,
|
|
|
756 -- to display the help message and raises Exit_From_Command_Line.
|
|
|
757 -- If an invalid switch is specified on the command line, this procedure
|
|
|
758 -- will display an error message and raises Invalid_Switch again.
|
|
|
759 --
|
|
|
760 -- This function automatically expands switches:
|
|
|
761 --
|
|
|
762 -- If Define_Prefix was called (for instance "-gnaty") and the user
|
|
|
763 -- specifies "-gnatycb" on the command line, then Getopt returns
|
|
|
764 -- "-gnatyc" and "-gnatyb" separately.
|
|
|
765 --
|
|
|
766 -- If Define_Alias was called (for instance "-gnatya = -gnatycb") then
|
|
|
767 -- the latter is returned (in this case it also expands -gnaty as per
|
|
|
768 -- the above.
|
|
|
769 --
|
|
|
770 -- The goal is to make handling as easy as possible by leaving as much
|
|
|
771 -- work as possible to this package.
|
|
|
772 --
|
|
|
773 -- As opposed to the standard Getopt, this one will analyze all sections
|
|
|
774 -- as defined by Define_Section, and automatically jump from one section to
|
|
|
775 -- the next.
|
|
|
776
|
|
|
777 ------------------------------
|
|
|
778 -- Generating command lines --
|
|
|
779 ------------------------------
|
|
|
780
|
|
|
781 -- Once the command line configuration has been created, you can build your
|
|
|
782 -- own command line. This will be done in general because you need to spawn
|
|
|
783 -- external tools from your application.
|
|
|
784
|
|
|
785 -- Although it could be done by concatenating strings, the following
|
|
|
786 -- subprograms will properly take care of grouping switches when possible,
|
|
|
787 -- so as to keep the command line as short as possible. They also provide a
|
|
|
788 -- way to remove a switch from an existing command line.
|
|
|
789
|
|
|
790 -- For instance:
|
|
|
791
|
|
|
792 -- declare
|
|
|
793 -- Config : Command_Line_Configuration;
|
|
|
794 -- Line : Command_Line;
|
|
|
795 -- Args : Argument_List_Access;
|
|
|
796
|
|
|
797 -- begin
|
|
|
798 -- Define_Switch (Config, "-gnatyc");
|
|
|
799 -- Define_Switch (Config, ...); -- for all valid switches
|
|
|
800 -- Define_Prefix (Config, "-gnaty");
|
|
|
801
|
|
|
802 -- Set_Configuration (Line, Config);
|
|
|
803 -- Add_Switch (Line, "-O2");
|
|
|
804 -- Add_Switch (Line, "-gnatyc");
|
|
|
805 -- Add_Switch (Line, "-gnatyd");
|
|
|
806 --
|
|
|
807 -- Build (Line, Args);
|
|
|
808 -- -- Args is now ["-O2", "-gnatycd"]
|
|
|
809 -- end;
|
|
|
810
|
|
|
811 type Command_Line is private;
|
|
|
812
|
|
|
813 procedure Set_Configuration
|
|
|
814 (Cmd : in out Command_Line;
|
|
|
815 Config : Command_Line_Configuration);
|
|
|
816 function Get_Configuration
|
|
|
817 (Cmd : Command_Line) return Command_Line_Configuration;
|
|
|
818 -- Set or retrieve the configuration used for that command line. The Config
|
|
|
819 -- must have been initialized first, by calling one of the Define_Switches
|
|
|
820 -- subprograms.
|
|
|
821
|
|
|
822 procedure Set_Command_Line
|
|
|
823 (Cmd : in out Command_Line;
|
|
|
824 Switches : String;
|
|
|
825 Getopt_Description : String := "";
|
|
|
826 Switch_Char : Character := '-');
|
|
|
827 -- Set the new content of the command line, by replacing the current
|
|
|
828 -- version with Switches.
|
|
|
829 --
|
|
|
830 -- The parsing of Switches is done through calls to Getopt, by passing
|
|
|
831 -- Getopt_Description as an argument. (A "*" is automatically prepended so
|
|
|
832 -- that all switches and command line arguments are accepted). If a config
|
|
|
833 -- was defined via Set_Configuration, the Getopt_Description parameter will
|
|
|
834 -- be ignored.
|
|
|
835 --
|
|
|
836 -- To properly handle switches that take parameters, you should document
|
|
|
837 -- them in Getopt_Description. Otherwise, the switch and its parameter will
|
|
|
838 -- be recorded as two separate command line arguments as returned by a
|
|
|
839 -- Command_Line_Iterator (which might be fine depending on your
|
|
|
840 -- application).
|
|
|
841 --
|
|
|
842 -- If the command line has sections (such as -bargs -cargs), then they
|
|
|
843 -- should be listed in the Sections parameter (as "-bargs -cargs").
|
|
|
844 --
|
|
|
845 -- This function can be used to reset Cmd by passing an empty string
|
|
|
846 --
|
|
131
|
847 -- If an invalid switch is found on the command line (i.e. wasn't defined
|
|
|
848 -- in the configuration via Define_Switch), and the configuration wasn't
|
|
|
849 -- set to accept all switches (by defining "*" as a valid switch), then an
|
|
111
|
850 -- exception Invalid_Switch is raised. The exception message indicates the
|
|
|
851 -- invalid switch.
|
|
|
852
|
|
|
853 procedure Add_Switch
|
|
|
854 (Cmd : in out Command_Line;
|
|
|
855 Switch : String;
|
|
|
856 Parameter : String := "";
|
|
|
857 Separator : Character := ASCII.NUL;
|
|
|
858 Section : String := "";
|
|
|
859 Add_Before : Boolean := False);
|
|
|
860 -- Add a new switch to the command line, and combine/group it with existing
|
|
|
861 -- switches if possible. Nothing is done if the switch already exists with
|
|
|
862 -- the same parameter.
|
|
|
863 --
|
|
|
864 -- If the Switch takes a parameter, the latter should be specified
|
|
|
865 -- separately, so that the association between the two is always correctly
|
|
|
866 -- recognized even if the order of switches on the command line changes.
|
|
|
867 -- For instance, you should pass "--check=full" as ("--check", "full") so
|
|
|
868 -- that Remove_Switch below can simply take "--check" in parameter. That
|
|
|
869 -- will automatically remove "full" as well. The value of the parameter is
|
|
|
870 -- never modified by this package.
|
|
|
871 --
|
|
|
872 -- On the other hand, you could decide to simply pass "--check=full" as
|
|
|
873 -- the Switch above, and then pass no parameter. This means that you need
|
|
|
874 -- to pass "--check=full" to Remove_Switch as well.
|
|
|
875 --
|
|
|
876 -- A Switch with a parameter will never be grouped with another switch to
|
|
|
877 -- avoid ambiguities as to what the parameter applies to.
|
|
|
878 --
|
|
|
879 -- If the switch is part of a section, then it should be specified so that
|
|
|
880 -- the switch is correctly placed in the command line, and the section
|
|
|
881 -- added if not already present. For example, to add the -g switch into the
|
|
|
882 -- -cargs section, you need to call (Cmd, "-g", Section => "-cargs").
|
|
|
883 --
|
|
|
884 -- [Separator], if specified, overrides the separator that was defined
|
|
|
885 -- through Define_Switch. For instance, if the switch was defined as
|
|
|
886 -- "-from:", the separator defaults to a space. But if your application
|
|
|
887 -- uses unusual separators not supported by GNAT.Command_Line (for instance
|
|
|
888 -- it requires ":"), you can specify this separator here.
|
|
|
889 --
|
|
|
890 -- For instance,
|
|
|
891 -- Add_Switch(Cmd, "-from", "bar", ':')
|
|
|
892 --
|
|
|
893 -- results in
|
|
|
894 -- -from:bar
|
|
|
895 --
|
|
|
896 -- rather than the default
|
|
|
897 -- -from bar
|
|
|
898 --
|
|
|
899 -- Note however that Getopt doesn't know how to handle ":" as a separator.
|
|
131
|
900 -- So the recommendation is to declare the switch as "-from!" (i.e. no
|
|
111
|
901 -- space between the switch and its parameter). Then Getopt will return
|
|
|
902 -- ":bar" as the parameter, and you can trim the ":" in your application.
|
|
|
903 --
|
|
|
904 -- Invalid_Section is raised if Section was not defined in the
|
|
|
905 -- configuration of the command line.
|
|
|
906 --
|
|
|
907 -- Add_Before allows insertion of the switch at the beginning of the
|
|
|
908 -- command line.
|
|
|
909
|
|
|
910 procedure Add_Switch
|
|
|
911 (Cmd : in out Command_Line;
|
|
|
912 Switch : String;
|
|
|
913 Parameter : String := "";
|
|
|
914 Separator : Character := ASCII.NUL;
|
|
|
915 Section : String := "";
|
|
|
916 Add_Before : Boolean := False;
|
|
|
917 Success : out Boolean);
|
|
|
918 -- Same as above, returning the status of the operation
|
|
|
919
|
|
|
920 procedure Remove_Switch
|
|
|
921 (Cmd : in out Command_Line;
|
|
|
922 Switch : String;
|
|
|
923 Remove_All : Boolean := False;
|
|
|
924 Has_Parameter : Boolean := False;
|
|
|
925 Section : String := "");
|
|
|
926 -- Remove Switch from the command line, and ungroup existing switches if
|
|
|
927 -- necessary.
|
|
|
928 --
|
|
|
929 -- The actual parameter to the switches are ignored. If for instance
|
|
|
930 -- you are removing "-foo", then "-foo param1" and "-foo param2" can
|
|
|
931 -- be removed.
|
|
|
932 --
|
|
|
933 -- If Remove_All is True, then all matching switches are removed, otherwise
|
|
|
934 -- only the first matching one is removed.
|
|
|
935 --
|
|
|
936 -- If Has_Parameter is set to True, then only switches having a parameter
|
|
|
937 -- are removed.
|
|
|
938 --
|
|
|
939 -- If the switch belongs to a section, then this section should be
|
|
|
940 -- specified: Remove_Switch (Cmd_Line, "-g", Section => "-cargs") called
|
|
|
941 -- on the command line "-g -cargs -g" will result in "-g", while if
|
|
|
942 -- called with (Cmd_Line, "-g") this will result in "-cargs -g".
|
|
|
943 -- If Remove_All is set, then both "-g" will be removed.
|
|
|
944
|
|
|
945 procedure Remove_Switch
|
|
|
946 (Cmd : in out Command_Line;
|
|
|
947 Switch : String;
|
|
|
948 Remove_All : Boolean := False;
|
|
|
949 Has_Parameter : Boolean := False;
|
|
|
950 Section : String := "";
|
|
|
951 Success : out Boolean);
|
|
|
952 -- Same as above, reporting the success of the operation (Success is False
|
|
|
953 -- if no switch was removed).
|
|
|
954
|
|
|
955 procedure Remove_Switch
|
|
|
956 (Cmd : in out Command_Line;
|
|
|
957 Switch : String;
|
|
|
958 Parameter : String;
|
|
|
959 Section : String := "");
|
|
|
960 -- Remove a switch with a specific parameter. If Parameter is the empty
|
|
|
961 -- string, then only a switch with no parameter will be removed.
|
|
|
962
|
|
|
963 procedure Free (Cmd : in out Command_Line);
|
|
|
964 -- Free the memory used by Cmd
|
|
|
965
|
|
|
966 ---------------
|
|
|
967 -- Iteration --
|
|
|
968 ---------------
|
|
|
969
|
|
|
970 -- When a command line was created with the above, you can then iterate
|
|
|
971 -- over its contents using the following iterator.
|
|
|
972
|
|
|
973 type Command_Line_Iterator is private;
|
|
|
974
|
|
|
975 procedure Start
|
|
|
976 (Cmd : in out Command_Line;
|
|
|
977 Iter : in out Command_Line_Iterator;
|
|
|
978 Expanded : Boolean := False);
|
|
|
979 -- Start iterating over the command line arguments. If Expanded is true,
|
|
|
980 -- then the arguments are not grouped and no alias is used. For instance,
|
|
|
981 -- "-gnatwv" and "-gnatwu" would be returned instead of "-gnatwuv".
|
|
|
982 --
|
|
|
983 -- The iterator becomes invalid if the command line is changed through a
|
|
|
984 -- call to Add_Switch, Remove_Switch or Set_Command_Line.
|
|
|
985
|
|
|
986 function Current_Switch (Iter : Command_Line_Iterator) return String;
|
|
|
987 function Is_New_Section (Iter : Command_Line_Iterator) return Boolean;
|
|
|
988 function Current_Section (Iter : Command_Line_Iterator) return String;
|
|
|
989 function Current_Separator (Iter : Command_Line_Iterator) return String;
|
|
|
990 function Current_Parameter (Iter : Command_Line_Iterator) return String;
|
|
|
991 -- Return the current switch and its parameter (or the empty string if
|
|
|
992 -- there is no parameter or the switch was added through Add_Switch
|
|
|
993 -- without specifying the parameter.
|
|
|
994 --
|
|
|
995 -- Separator is the string that goes between the switch and its separator.
|
|
|
996 -- It could be the empty string if they should be concatenated, or a space
|
|
|
997 -- for instance. When printing, you should not add any other character.
|
|
|
998
|
|
|
999 function Has_More (Iter : Command_Line_Iterator) return Boolean;
|
|
|
1000 -- Return True if there are more switches to be returned
|
|
|
1001
|
|
|
1002 procedure Next (Iter : in out Command_Line_Iterator);
|
|
|
1003 -- Move to the next switch
|
|
|
1004
|
|
|
1005 procedure Build
|
|
|
1006 (Line : in out Command_Line;
|
|
|
1007 Args : out GNAT.OS_Lib.Argument_List_Access;
|
|
|
1008 Expanded : Boolean := False;
|
|
|
1009 Switch_Char : Character := '-');
|
|
|
1010 -- This is a wrapper using the Command_Line_Iterator. It provides a simple
|
|
|
1011 -- way to get all switches (grouped as much as possible), and possibly
|
|
|
1012 -- create an Opt_Parser.
|
|
|
1013 --
|
|
|
1014 -- Args must be freed by the caller.
|
|
|
1015 --
|
|
|
1016 -- Expanded has the same meaning as in Start.
|
|
|
1017
|
|
|
1018 procedure Try_Help;
|
|
|
1019 -- Output a message on standard error to indicate how to get the usage for
|
|
|
1020 -- the executable. This procedure should only be called when the executable
|
|
|
1021 -- accepts switch --help. When this procedure is called by executable xxx,
|
|
|
1022 -- the following message is displayed on standard error:
|
|
|
1023 -- try "xxx --help" for more information.
|
|
|
1024
|
|
|
1025 private
|
|
|
1026
|
|
|
1027 Max_Depth : constant := 100;
|
|
|
1028 -- Maximum depth of subdirectories
|
|
|
1029
|
|
|
1030 Max_Path_Length : constant := 1024;
|
|
|
1031 -- Maximum length of relative path
|
|
|
1032
|
|
|
1033 type Depth is range 1 .. Max_Depth;
|
|
|
1034
|
|
|
1035 type Level is record
|
|
|
1036 Name_Last : Natural := 0;
|
|
|
1037 Dir : GNAT.Directory_Operations.Dir_Type;
|
|
|
1038 end record;
|
|
|
1039
|
|
|
1040 type Level_Array is array (Depth) of Level;
|
|
|
1041
|
|
|
1042 type Section_Number is new Natural range 0 .. 65534;
|
|
|
1043 for Section_Number'Size use 16;
|
|
|
1044
|
|
|
1045 type Parameter_Type is record
|
|
|
1046 Arg_Num : Positive;
|
|
|
1047 First : Positive;
|
|
|
1048 Last : Natural;
|
|
|
1049 Extra : Character;
|
|
|
1050 end record;
|
|
|
1051
|
|
|
1052 type Is_Switch_Type is array (Natural range <>) of Boolean;
|
|
|
1053 pragma Pack (Is_Switch_Type);
|
|
|
1054
|
|
|
1055 type Section_Type is array (Natural range <>) of Section_Number;
|
|
|
1056 pragma Pack (Section_Type);
|
|
|
1057
|
|
|
1058 type Expansion_Iterator is limited record
|
|
|
1059 Start : Positive := 1;
|
|
|
1060 -- Position of the first character of the relative path to check against
|
|
|
1061 -- the pattern.
|
|
|
1062
|
|
|
1063 Dir_Name : String (1 .. Max_Path_Length);
|
|
|
1064
|
|
|
1065 Current_Depth : Depth := 1;
|
|
|
1066
|
|
|
1067 Levels : Level_Array;
|
|
|
1068
|
|
|
1069 Regexp : GNAT.Regexp.Regexp;
|
|
|
1070 -- Regular expression built with the pattern
|
|
|
1071
|
|
|
1072 Maximum_Depth : Depth := 1;
|
|
|
1073 -- The maximum depth of directories, reflecting the number of directory
|
|
|
1074 -- separators in the pattern.
|
|
|
1075 end record;
|
|
|
1076
|
|
|
1077 type Opt_Parser_Data (Arg_Count : Natural) is record
|
|
|
1078 Arguments : GNAT.OS_Lib.Argument_List_Access;
|
|
|
1079 -- null if reading from the command line
|
|
|
1080
|
|
|
1081 The_Parameter : Parameter_Type;
|
|
|
1082 The_Separator : Character;
|
|
|
1083 The_Switch : Parameter_Type;
|
|
|
1084 -- This type and this variable are provided to store the current switch
|
|
|
1085 -- and parameter.
|
|
|
1086
|
|
|
1087 Is_Switch : Is_Switch_Type (1 .. Arg_Count) := (others => False);
|
|
|
1088 -- Indicates wich arguments on the command line are considered not be
|
|
|
1089 -- switches or parameters to switches (leaving e.g. filenames,...)
|
|
|
1090
|
|
|
1091 Section : Section_Type (1 .. Arg_Count) := (others => 1);
|
|
|
1092 -- Contains the number of the section associated with the current
|
|
|
1093 -- switch. If this number is 0, then it is a section delimiter, which is
|
|
|
1094 -- never returned by GetOpt.
|
|
|
1095
|
|
|
1096 Current_Argument : Natural := 1;
|
|
|
1097 -- Number of the current argument parsed on the command line
|
|
|
1098
|
|
|
1099 Current_Index : Natural := 1;
|
|
|
1100 -- Index in the current argument of the character to be processed
|
|
|
1101
|
|
|
1102 Current_Section : Section_Number := 1;
|
|
|
1103
|
|
|
1104 Expansion_It : aliased Expansion_Iterator;
|
|
|
1105 -- When Get_Argument is expanding a file name, this is the iterator used
|
|
|
1106
|
|
|
1107 In_Expansion : Boolean := False;
|
|
|
1108 -- True if we are expanding a file
|
|
|
1109
|
|
|
1110 Switch_Character : Character := '-';
|
|
|
1111 -- The character at the beginning of the command line arguments,
|
|
|
1112 -- indicating the beginning of a switch.
|
|
|
1113
|
|
|
1114 Stop_At_First : Boolean := False;
|
|
|
1115 -- If it is True then Getopt stops at the first non-switch argument
|
|
|
1116 end record;
|
|
|
1117
|
|
|
1118 Command_Line_Parser_Data : aliased Opt_Parser_Data
|
|
|
1119 (Ada.Command_Line.Argument_Count);
|
|
|
1120 -- The internal data used when parsing the command line
|
|
|
1121
|
|
|
1122 type Opt_Parser is access all Opt_Parser_Data;
|
|
|
1123 Command_Line_Parser : constant Opt_Parser :=
|
|
|
1124 Command_Line_Parser_Data'Access;
|
|
|
1125
|
|
|
1126 type Switch_Type is (Switch_Untyped,
|
|
|
1127 Switch_Boolean,
|
|
|
1128 Switch_Integer,
|
|
131
|
1129 Switch_String,
|
|
|
1130 Switch_Callback);
|
|
111
|
1131
|
|
|
1132 type Switch_Definition (Typ : Switch_Type := Switch_Untyped) is record
|
|
|
1133 Switch : GNAT.OS_Lib.String_Access;
|
|
|
1134 Long_Switch : GNAT.OS_Lib.String_Access;
|
|
|
1135 Section : GNAT.OS_Lib.String_Access;
|
|
|
1136 Help : GNAT.OS_Lib.String_Access;
|
|
|
1137
|
|
|
1138 Argument : GNAT.OS_Lib.String_Access;
|
|
|
1139 -- null if "ARG".
|
|
|
1140 -- Name of the argument for this switch.
|
|
|
1141
|
|
|
1142 case Typ is
|
|
|
1143 when Switch_Untyped =>
|
|
|
1144 null;
|
|
|
1145 when Switch_Boolean =>
|
|
|
1146 Boolean_Output : access Boolean;
|
|
|
1147 Boolean_Value : Boolean; -- will set Output to that value
|
|
|
1148 when Switch_Integer =>
|
|
|
1149 Integer_Output : access Integer;
|
|
|
1150 Integer_Initial : Integer;
|
|
|
1151 Integer_Default : Integer;
|
|
|
1152 when Switch_String =>
|
|
|
1153 String_Output : access GNAT.Strings.String_Access;
|
|
131
|
1154 when Switch_Callback =>
|
|
|
1155 Callback : Value_Callback;
|
|
111
|
1156 end case;
|
|
|
1157 end record;
|
|
|
1158 type Switch_Definitions is array (Natural range <>) of Switch_Definition;
|
|
|
1159 type Switch_Definitions_List is access all Switch_Definitions;
|
|
|
1160 -- [Switch] includes the leading '-'
|
|
|
1161
|
|
|
1162 type Alias_Definition is record
|
|
|
1163 Alias : GNAT.OS_Lib.String_Access;
|
|
|
1164 Expansion : GNAT.OS_Lib.String_Access;
|
|
|
1165 Section : GNAT.OS_Lib.String_Access;
|
|
|
1166 end record;
|
|
|
1167 type Alias_Definitions is array (Natural range <>) of Alias_Definition;
|
|
|
1168 type Alias_Definitions_List is access all Alias_Definitions;
|
|
|
1169
|
|
|
1170 type Command_Line_Configuration_Record is record
|
|
|
1171 Prefixes : GNAT.OS_Lib.Argument_List_Access;
|
|
|
1172 -- The list of prefixes
|
|
|
1173
|
|
|
1174 Sections : GNAT.OS_Lib.Argument_List_Access;
|
|
|
1175 -- The list of sections
|
|
|
1176
|
|
|
1177 Star_Switch : Boolean := False;
|
|
|
1178 -- Whether switches not described in this configuration should be
|
|
|
1179 -- returned to the user (True). If False, an exception Invalid_Switch
|
|
|
1180 -- is raised.
|
|
|
1181
|
|
|
1182 Aliases : Alias_Definitions_List;
|
|
|
1183 Usage : GNAT.OS_Lib.String_Access;
|
|
|
1184 Help : GNAT.OS_Lib.String_Access;
|
|
|
1185 Help_Msg : GNAT.OS_Lib.String_Access;
|
|
|
1186 Switches : Switch_Definitions_List;
|
|
|
1187 -- List of expected switches (Used when expanding switch groups)
|
|
|
1188 end record;
|
|
|
1189 type Command_Line_Configuration is access Command_Line_Configuration_Record;
|
|
|
1190
|
|
|
1191 type Command_Line is record
|
|
|
1192 Config : Command_Line_Configuration;
|
|
|
1193 Expanded : GNAT.OS_Lib.Argument_List_Access;
|
|
|
1194
|
|
|
1195 Params : GNAT.OS_Lib.Argument_List_Access;
|
|
|
1196 -- Parameter for the corresponding switch in Expanded. The first
|
|
|
1197 -- character is the separator (or ASCII.NUL if there is no separator).
|
|
|
1198
|
|
|
1199 Sections : GNAT.OS_Lib.Argument_List_Access;
|
|
|
1200 -- The list of sections
|
|
|
1201
|
|
|
1202 Coalesce : GNAT.OS_Lib.Argument_List_Access;
|
|
|
1203 Coalesce_Params : GNAT.OS_Lib.Argument_List_Access;
|
|
|
1204 Coalesce_Sections : GNAT.OS_Lib.Argument_List_Access;
|
|
|
1205 -- Cached version of the command line. This is recomputed every time
|
|
|
1206 -- the command line changes. Switches are grouped as much as possible,
|
|
|
1207 -- and aliases are used to reduce the length of the command line. The
|
|
|
1208 -- parameters are not allocated, they point into Params, so they must
|
|
|
1209 -- not be freed.
|
|
|
1210 end record;
|
|
|
1211
|
|
|
1212 type Command_Line_Iterator is record
|
|
|
1213 List : GNAT.OS_Lib.Argument_List_Access;
|
|
|
1214 Sections : GNAT.OS_Lib.Argument_List_Access;
|
|
|
1215 Params : GNAT.OS_Lib.Argument_List_Access;
|
|
|
1216 Current : Natural;
|
|
|
1217 end record;
|
|
|
1218
|
|
|
1219 end GNAT.Command_Line;
|
