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--                                                                          --
9--                     Copyright (C) 1999-2012, AdaCore                     --
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
280with Ada.Command_Line;
281
282with GNAT.Directory_Operations;
283with GNAT.OS_Lib;
284with GNAT.Regexp;
285with GNAT.Strings;
286
287package 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 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
681   procedure Set_Usage
682     (Config   : in out Command_Line_Configuration;
683      Usage    : String := "[switches] [arguments]";
684      Help     : String := "";
685      Help_Msg : String := "");
686   --  Defines the general format of the call to the application, and a short
687   --  help text. These are both displayed by Display_Help. When a non-empty
688   --  Help_Msg is given, it is used by Display_Help instead of the
689   --  automatically generated list of supported switches.
690
691   procedure Display_Help (Config : Command_Line_Configuration);
692   --  Display the help for the tool (ie its usage, and its supported switches)
693
694   function Get_Switches
695     (Config      : Command_Line_Configuration;
696      Switch_Char : Character := '-';
697      Section     : String := "") return String;
698   --  Get the switches list as expected by Getopt, for a specific section of
699   --  the command line. This list is built using all switches defined
700   --  previously via Define_Switch above.
701
702   function Section_Delimiters
703     (Config : Command_Line_Configuration) return String;
704   --  Return a string suitable for use in Initialize_Option_Scan
705
706   procedure Free (Config : in out Command_Line_Configuration);
707   --  Free the memory used by Config
708
709   type Switch_Handler is access procedure
710     (Switch    : String;
711      Parameter : String;
712      Section   : String);
713   --  Called when a switch is found on the command line. Switch includes
714   --  any leading '-' that was specified in Define_Switch. This is slightly
715   --  different from the functional version of Getopt above, for which
716   --  Full_Switch omits the first leading '-'.
717
718   Exit_From_Command_Line : exception;
719   --  Emitted when the program should exit. This is called when Getopt below
720   --  has seen -h, --help or an invalid switch.
721
722   procedure Getopt
723     (Config      : Command_Line_Configuration;
724      Callback    : Switch_Handler := null;
725      Parser      : Opt_Parser := Command_Line_Parser;
726      Concatenate : Boolean := True);
727   --  Similar to the standard Getopt function. For each switch found on the
728   --  command line, this calls Callback, if the switch is not handled
729   --  automatically.
730   --
731   --  The list of valid switches are the ones from the configuration. The
732   --  switches that were declared through Define_Switch with an Output
733   --  parameter are never returned (and result in a modification of the Output
734   --  variable). This function will in fact never call [Callback] if all
735   --  switches were handled automatically and there is nothing left to do.
736   --
737   --  The option Concatenate is identical to the one of the standard Getopt
738   --  function.
739   --
740   --  This procedure automatically adds -h and --help to the valid switches,
741   --  to display the help message and raises Exit_From_Command_Line.
742   --  If an invalid switch is specified on the command line, this procedure
743   --  will display an error message and raises Invalid_Switch again.
744   --
745   --  This function automatically expands switches:
746   --
747   --    If Define_Prefix was called (for instance "-gnaty") and the user
748   --    specifies "-gnatycb" on the command line, then Getopt returns
749   --    "-gnatyc" and "-gnatyb" separately.
750   --
751   --    If Define_Alias was called (for instance "-gnatya = -gnatycb") then
752   --    the latter is returned (in this case it also expands -gnaty as per
753   --    the above.
754   --
755   --  The goal is to make handling as easy as possible by leaving as much
756   --  work as possible to this package.
757   --
758   --  As opposed to the standard Getopt, this one will analyze all sections
759   --  as defined by Define_Section, and automatically jump from one section to
760   --  the next.
761
762   ------------------------------
763   -- Generating command lines --
764   ------------------------------
765
766   --  Once the command line configuration has been created, you can build your
767   --  own command line. This will be done in general because you need to spawn
768   --  external tools from your application.
769
770   --  Although it could be done by concatenating strings, the following
771   --  subprograms will properly take care of grouping switches when possible,
772   --  so as to keep the command line as short as possible. They also provide a
773   --  way to remove a switch from an existing command line.
774
775   --  For instance:
776
777   --      declare
778   --         Config : Command_Line_Configuration;
779   --         Line : Command_Line;
780   --         Args : Argument_List_Access;
781
782   --      begin
783   --         Define_Switch (Config, "-gnatyc");
784   --         Define_Switch (Config, ...);  --  for all valid switches
785   --         Define_Prefix (Config, "-gnaty");
786
787   --         Set_Configuration (Line, Config);
788   --         Add_Switch (Line, "-O2");
789   --         Add_Switch (Line, "-gnatyc");
790   --         Add_Switch (Line, "-gnatyd");
791   --
792   --         Build (Line, Args);
793   --         --   Args is now  ["-O2", "-gnatycd"]
794   --      end;
795
796   type Command_Line is private;
797
798   procedure Set_Configuration
799     (Cmd    : in out Command_Line;
800      Config : Command_Line_Configuration);
801   function Get_Configuration
802     (Cmd : Command_Line) return Command_Line_Configuration;
803   --  Set or retrieve the configuration used for that command line. The Config
804   --  must have been initialized first, by calling one of the Define_Switches
805   --  subprograms.
806
807   procedure Set_Command_Line
808     (Cmd                : in out Command_Line;
809      Switches           : String;
810      Getopt_Description : String    := "";
811      Switch_Char        : Character := '-');
812   --  Set the new content of the command line, by replacing the current
813   --  version with Switches.
814   --
815   --  The parsing of Switches is done through calls to Getopt, by passing
816   --  Getopt_Description as an argument. (A "*" is automatically prepended so
817   --  that all switches and command line arguments are accepted). If a config
818   --  was defined via Set_Configuration, the Getopt_Description parameter will
819   --  be ignored.
820   --
821   --  To properly handle switches that take parameters, you should document
822   --  them in Getopt_Description. Otherwise, the switch and its parameter will
823   --  be recorded as two separate command line arguments as returned by a
824   --  Command_Line_Iterator (which might be fine depending on your
825   --  application).
826   --
827   --  If the command line has sections (such as -bargs -cargs), then they
828   --  should be listed in the Sections parameter (as "-bargs -cargs").
829   --
830   --  This function can be used to reset Cmd by passing an empty string
831   --
832   --  If an invalid switch is found on the command line (ie wasn't defined in
833   --  the configuration via Define_Switch), and the configuration wasn't set
834   --  to accept all switches (by defining "*" as a valid switch), then an
835   --  exception Invalid_Switch is raised. The exception message indicates the
836   --  invalid switch.
837
838   procedure Add_Switch
839     (Cmd        : in out Command_Line;
840      Switch     : String;
841      Parameter  : String    := "";
842      Separator  : Character := ASCII.NUL;
843      Section    : String    := "";
844      Add_Before : Boolean   := False);
845   --  Add a new switch to the command line, and combine/group it with existing
846   --  switches if possible. Nothing is done if the switch already exists with
847   --  the same parameter.
848   --
849   --  If the Switch takes a parameter, the latter should be specified
850   --  separately, so that the association between the two is always correctly
851   --  recognized even if the order of switches on the command line changes.
852   --  For instance, you should pass "--check=full" as ("--check", "full") so
853   --  that Remove_Switch below can simply take "--check" in parameter. That
854   --  will automatically remove "full" as well. The value of the parameter is
855   --  never modified by this package.
856   --
857   --  On the other hand, you could decide to simply pass "--check=full" as
858   --  the Switch above, and then pass no parameter. This means that you need
859   --  to pass "--check=full" to Remove_Switch as well.
860   --
861   --  A Switch with a parameter will never be grouped with another switch to
862   --  avoid ambiguities as to what the parameter applies to.
863   --
864   --  If the switch is part of a section, then it should be specified so that
865   --  the switch is correctly placed in the command line, and the section
866   --  added if not already present. For example, to add the -g switch into the
867   --  -cargs section, you need to call (Cmd, "-g", Section => "-cargs").
868   --
869   --  [Separator], if specified, overrides the separator that was defined
870   --  through Define_Switch. For instance, if the switch was defined as
871   --  "-from:", the separator defaults to a space. But if your application
872   --  uses unusual separators not supported by GNAT.Command_Line (for instance
873   --  it requires ":"), you can specify this separator here.
874   --
875   --  For instance,
876   --     Add_Switch(Cmd, "-from", "bar", ':')
877   --
878   --  results in
879   --     -from:bar
880   --
881   --  rather than the default
882   --     -from bar
883   --
884   --  Note however that Getopt doesn't know how to handle ":" as a separator.
885   --  So the recommendation is to declare the switch as "-from!" (ie no
886   --  space between the switch and its parameter). Then Getopt will return
887   --  ":bar" as the parameter, and you can trim the ":" in your application.
888   --
889   --  Invalid_Section is raised if Section was not defined in the
890   --  configuration of the command line.
891   --
892   --  Add_Before allows insertion of the switch at the beginning of the
893   --  command line.
894
895   procedure Add_Switch
896     (Cmd        : in out Command_Line;
897      Switch     : String;
898      Parameter  : String    := "";
899      Separator  : Character := ASCII.NUL;
900      Section    : String    := "";
901      Add_Before : Boolean   := False;
902      Success    : out Boolean);
903   --  Same as above, returning the status of the operation
904
905   procedure Remove_Switch
906     (Cmd           : in out Command_Line;
907      Switch        : String;
908      Remove_All    : Boolean := False;
909      Has_Parameter : Boolean := False;
910      Section       : String := "");
911   --  Remove Switch from the command line, and ungroup existing switches if
912   --  necessary.
913   --
914   --  The actual parameter to the switches are ignored. If for instance
915   --  you are removing "-foo", then "-foo param1" and "-foo param2" can
916   --  be removed.
917   --
918   --  If Remove_All is True, then all matching switches are removed, otherwise
919   --  only the first matching one is removed.
920   --
921   --  If Has_Parameter is set to True, then only switches having a parameter
922   --  are removed.
923   --
924   --  If the switch belongs to a section, then this section should be
925   --  specified: Remove_Switch (Cmd_Line, "-g", Section => "-cargs") called
926   --  on the command line "-g -cargs -g" will result in "-g", while if
927   --  called with (Cmd_Line, "-g") this will result in "-cargs -g".
928   --  If Remove_All is set, then both "-g" will be removed.
929
930   procedure Remove_Switch
931     (Cmd           : in out Command_Line;
932      Switch        : String;
933      Remove_All    : Boolean := False;
934      Has_Parameter : Boolean := False;
935      Section       : String  := "";
936      Success       : out Boolean);
937   --  Same as above, reporting the success of the operation (Success is False
938   --  if no switch was removed).
939
940   procedure Remove_Switch
941     (Cmd       : in out Command_Line;
942      Switch    : String;
943      Parameter : String;
944      Section   : String := "");
945   --  Remove a switch with a specific parameter. If Parameter is the empty
946   --  string, then only a switch with no parameter will be removed.
947
948   procedure Free (Cmd : in out Command_Line);
949   --  Free the memory used by Cmd
950
951   ---------------
952   -- Iteration --
953   ---------------
954
955   --  When a command line was created with the above, you can then iterate
956   --  over its contents using the following iterator.
957
958   type Command_Line_Iterator is private;
959
960   procedure Start
961     (Cmd      : in out Command_Line;
962      Iter     : in out Command_Line_Iterator;
963      Expanded : Boolean := False);
964   --  Start iterating over the command line arguments. If Expanded is true,
965   --  then the arguments are not grouped and no alias is used. For instance,
966   --  "-gnatwv" and "-gnatwu" would be returned instead of "-gnatwuv".
967   --
968   --  The iterator becomes invalid if the command line is changed through a
969   --  call to Add_Switch, Remove_Switch or Set_Command_Line.
970
971   function Current_Switch    (Iter : Command_Line_Iterator) return String;
972   function Is_New_Section    (Iter : Command_Line_Iterator) return Boolean;
973   function Current_Section   (Iter : Command_Line_Iterator) return String;
974   function Current_Separator (Iter : Command_Line_Iterator) return String;
975   function Current_Parameter (Iter : Command_Line_Iterator) return String;
976   --  Return the current switch and its parameter (or the empty string if
977   --  there is no parameter or the switch was added through Add_Switch
978   --  without specifying the parameter.
979   --
980   --  Separator is the string that goes between the switch and its separator.
981   --  It could be the empty string if they should be concatenated, or a space
982   --  for instance. When printing, you should not add any other character.
983
984   function Has_More (Iter : Command_Line_Iterator) return Boolean;
985   --  Return True if there are more switches to be returned
986
987   procedure Next (Iter : in out Command_Line_Iterator);
988   --  Move to the next switch
989
990   procedure Build
991     (Line        : in out Command_Line;
992      Args        : out GNAT.OS_Lib.Argument_List_Access;
993      Expanded    : Boolean := False;
994      Switch_Char : Character := '-');
995   --  This is a wrapper using the Command_Line_Iterator. It provides a simple
996   --  way to get all switches (grouped as much as possible), and possibly
997   --  create an Opt_Parser.
998   --
999   --  Args must be freed by the caller.
1000   --
1001   --  Expanded has the same meaning as in Start.
1002
1003private
1004
1005   Max_Depth : constant := 100;
1006   --  Maximum depth of subdirectories
1007
1008   Max_Path_Length : constant := 1024;
1009   --  Maximum length of relative path
1010
1011   type Depth is range 1 .. Max_Depth;
1012
1013   type Level is record
1014      Name_Last : Natural := 0;
1015      Dir       : GNAT.Directory_Operations.Dir_Type;
1016   end record;
1017
1018   type Level_Array is array (Depth) of Level;
1019
1020   type Section_Number is new Natural range 0 .. 65534;
1021   for Section_Number'Size use 16;
1022
1023   type Parameter_Type is record
1024      Arg_Num : Positive;
1025      First   : Positive;
1026      Last    : Positive;
1027      Extra   : Character;
1028   end record;
1029
1030   type Is_Switch_Type is array (Natural range <>) of Boolean;
1031   pragma Pack (Is_Switch_Type);
1032
1033   type Section_Type is array (Natural range <>) of Section_Number;
1034   pragma Pack (Section_Type);
1035
1036   type Expansion_Iterator is limited record
1037      Start : Positive := 1;
1038      --  Position of the first character of the relative path to check against
1039      --  the pattern.
1040
1041      Dir_Name : String (1 .. Max_Path_Length);
1042
1043      Current_Depth : Depth := 1;
1044
1045      Levels : Level_Array;
1046
1047      Regexp : GNAT.Regexp.Regexp;
1048      --  Regular expression built with the pattern
1049
1050      Maximum_Depth : Depth := 1;
1051      --  The maximum depth of directories, reflecting the number of directory
1052      --  separators in the pattern.
1053   end record;
1054
1055   type Opt_Parser_Data (Arg_Count : Natural) is record
1056      Arguments : GNAT.OS_Lib.Argument_List_Access;
1057      --  null if reading from the command line
1058
1059      The_Parameter : Parameter_Type;
1060      The_Separator : Character;
1061      The_Switch    : Parameter_Type;
1062      --  This type and this variable are provided to store the current switch
1063      --  and parameter.
1064
1065      Is_Switch : Is_Switch_Type (1 .. Arg_Count) := (others => False);
1066      --  Indicates wich arguments on the command line are considered not be
1067      --  switches or parameters to switches (leaving e.g. filenames,...)
1068
1069      Section : Section_Type (1 .. Arg_Count) := (others => 1);
1070      --  Contains the number of the section associated with the current
1071      --  switch. If this number is 0, then it is a section delimiter, which is
1072      --  never returned by GetOpt.
1073
1074      Current_Argument : Natural := 1;
1075      --  Number of the current argument parsed on the command line
1076
1077      Current_Index : Natural := 1;
1078      --  Index in the current argument of the character to be processed
1079
1080      Current_Section : Section_Number := 1;
1081
1082      Expansion_It : aliased Expansion_Iterator;
1083      --  When Get_Argument is expanding a file name, this is the iterator used
1084
1085      In_Expansion : Boolean := False;
1086      --  True if we are expanding a file
1087
1088      Switch_Character : Character := '-';
1089      --  The character at the beginning of the command line arguments,
1090      --  indicating the beginning of a switch.
1091
1092      Stop_At_First : Boolean := False;
1093      --  If it is True then Getopt stops at the first non-switch argument
1094   end record;
1095
1096   Command_Line_Parser_Data : aliased Opt_Parser_Data
1097                                        (Ada.Command_Line.Argument_Count);
1098   --  The internal data used when parsing the command line
1099
1100   type Opt_Parser is access all Opt_Parser_Data;
1101   Command_Line_Parser : constant Opt_Parser :=
1102                           Command_Line_Parser_Data'Access;
1103
1104   type Switch_Type is (Switch_Untyped,
1105                        Switch_Boolean,
1106                        Switch_Integer,
1107                        Switch_String);
1108
1109   type Switch_Definition (Typ : Switch_Type := Switch_Untyped) is record
1110      Switch      : GNAT.OS_Lib.String_Access;
1111      Long_Switch : GNAT.OS_Lib.String_Access;
1112      Section     : GNAT.OS_Lib.String_Access;
1113      Help        : GNAT.OS_Lib.String_Access;
1114
1115      Argument    : GNAT.OS_Lib.String_Access;
1116      --  null if "ARG".
1117      --  Name of the argument for this switch.
1118
1119      case Typ is
1120         when Switch_Untyped =>
1121            null;
1122         when Switch_Boolean =>
1123            Boolean_Output : access Boolean;
1124            Boolean_Value  : Boolean;  --  will set Output to that value
1125         when Switch_Integer =>
1126            Integer_Output  : access Integer;
1127            Integer_Initial : Integer;
1128            Integer_Default : Integer;
1129         when Switch_String =>
1130            String_Output   : access GNAT.Strings.String_Access;
1131      end case;
1132   end record;
1133   type Switch_Definitions is array (Natural range <>) of Switch_Definition;
1134   type Switch_Definitions_List is access all Switch_Definitions;
1135   --  [Switch] includes the leading '-'
1136
1137   type Alias_Definition is record
1138      Alias     : GNAT.OS_Lib.String_Access;
1139      Expansion : GNAT.OS_Lib.String_Access;
1140      Section   : GNAT.OS_Lib.String_Access;
1141   end record;
1142   type Alias_Definitions is array (Natural range <>) of Alias_Definition;
1143   type Alias_Definitions_List is access all Alias_Definitions;
1144
1145   type Command_Line_Configuration_Record is record
1146      Prefixes : GNAT.OS_Lib.Argument_List_Access;
1147      --  The list of prefixes
1148
1149      Sections : GNAT.OS_Lib.Argument_List_Access;
1150      --  The list of sections
1151
1152      Star_Switch : Boolean := False;
1153      --  Whether switches not described in this configuration should be
1154      --  returned to the user (True). If False, an exception Invalid_Switch
1155      --  is raised.
1156
1157      Aliases  : Alias_Definitions_List;
1158      Usage    : GNAT.OS_Lib.String_Access;
1159      Help     : GNAT.OS_Lib.String_Access;
1160      Help_Msg : GNAT.OS_Lib.String_Access;
1161      Switches : Switch_Definitions_List;
1162      --  List of expected switches (Used when expanding switch groups)
1163   end record;
1164   type Command_Line_Configuration is access Command_Line_Configuration_Record;
1165
1166   type Command_Line is record
1167      Config   : Command_Line_Configuration;
1168      Expanded : GNAT.OS_Lib.Argument_List_Access;
1169
1170      Params : GNAT.OS_Lib.Argument_List_Access;
1171      --  Parameter for the corresponding switch in Expanded. The first
1172      --  character is the separator (or ASCII.NUL if there is no separator).
1173
1174      Sections : GNAT.OS_Lib.Argument_List_Access;
1175      --  The list of sections
1176
1177      Coalesce          : GNAT.OS_Lib.Argument_List_Access;
1178      Coalesce_Params   : GNAT.OS_Lib.Argument_List_Access;
1179      Coalesce_Sections : GNAT.OS_Lib.Argument_List_Access;
1180      --  Cached version of the command line. This is recomputed every time
1181      --  the command line changes. Switches are grouped as much as possible,
1182      --  and aliases are used to reduce the length of the command line. The
1183      --  parameters are not allocated, they point into Params, so they must
1184      --  not be freed.
1185   end record;
1186
1187   type Command_Line_Iterator is record
1188      List     : GNAT.OS_Lib.Argument_List_Access;
1189      Sections : GNAT.OS_Lib.Argument_List_Access;
1190      Params   : GNAT.OS_Lib.Argument_List_Access;
1191      Current  : Natural;
1192   end record;
1193
1194end GNAT.Command_Line;
1195