Subversion Repositories openrisc

------------------------------------------------------------------------------

--                                                                          --

--                         GNAT COMPILER COMPONENTS                         --

--                                                                          --

--                    G N A T . C O M M A N D _ L I N E                     --

--                                                                          --

--                                 S p e c                                  --

--                                                                          --

--                     Copyright (C) 1999-2011, AdaCore                     --

--                                                                          --

-- GNAT is free software;  you can  redistribute it  and/or modify it under --

-- terms of the  GNU General Public License as published  by the Free Soft- --

-- ware  Foundation;  either version 3,  or (at your option) any later ver- --

-- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --

-- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --

-- or FITNESS FOR A PARTICULAR PURPOSE.                                     --

--                                                                          --

-- As a special exception under Section 7 of GPL version 3, you are granted --

-- additional permissions described in the GCC Runtime Library Exception,   --

-- version 3.1, as published by the Free Software Foundation.               --

--                                                                          --

-- You should have received a copy of the GNU General Public License and    --

-- a copy of the GCC Runtime Library Exception along with this program;     --

-- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --

-- <http://www.gnu.org/licenses/>.                                          --

--                                                                          --

-- GNAT was originally developed  by the GNAT team at  New York University. --

-- Extensive contributions were provided by Ada Core Technologies Inc.      --

--                                                                          --

------------------------------------------------------------------------------

--  High level package for command line parsing and manipulation

----------------------------------------

-- Simple Parsing of the Command Line --

----------------------------------------

--  This package provides an interface for parsing command line arguments,

--  when they are either read from Ada.Command_Line or read from a string list.

--  As shown in the example below, one should first retrieve the switches

--  (special command line arguments starting with '-' by default) and their

--  parameters, and then the rest of the command line arguments.

--

--  While it may appear easy to parse the command line arguments with

--  Ada.Command_Line, there are in fact lots of special cases to handle in some

--  applications. Those are fully managed by GNAT.Command_Line. Among these are

--  switches with optional parameters, grouping switches (for instance "-ab"

--  might mean the same as "-a -b"), various characters to separate a switch

--  and its parameter (or none: "-a 1" and "-a1" are generally the same, which

--  can introduce confusion with grouped switches),...

--

--  begin

--     loop

--        case Getopt ("a b: ad") is  -- Accepts '-a', '-ad', or '-b argument'

--           when ASCII.NUL => exit;

--           when 'a' =>

--                 if Full_Switch = "a" then

--                    Put_Line ("Got a");

--                 else

--                    Put_Line ("Got ad");

--                 end if;

--           when 'b' => Put_Line ("Got b + " & Parameter);

--           when others =>

--              raise Program_Error;         -- cannot occur!

--        end case;

--     end loop;

--     loop

--        declare

--           S : constant String := Get_Argument (Do_Expansion => True);

--        begin

--           exit when S'Length = 0;

--           Put_Line ("Got " & S);

--        end;

--     end loop;

--  exception

--     when Invalid_Switch    => Put_Line ("Invalid Switch " & Full_Switch);

--     when Invalid_Parameter => Put_Line ("No parameter for " & Full_Switch);

--  end;

--------------

-- Sections --

--------------

--  A more complicated example would involve the use of sections for the

--  switches, as for instance in gnatmake. The same command line is used to

--  provide switches for several tools. Each tool recognizes its switches by

--  separating them with special switches that act as section separators.

--  Each section acts as a command line of its own.

--  begin

--     Initialize_Option_Scan ('-', False, "largs bargs cargs");

--     loop

--        --  Same loop as above to get switches and arguments

--     end loop;

--     Goto_Section ("bargs");

--     loop

--        --  Same loop as above to get switches and arguments

--        --  The supported switches in Getopt might be different

--     end loop;

--     Goto_Section ("cargs");

--     loop

--        --  Same loop as above to get switches and arguments

--        --  The supported switches in Getopt might be different

--     end loop;

--  end;

-------------------------------

-- Parsing a List of Strings --

-------------------------------

--  The examples above show how to parse the command line when the arguments

--  are read directly from Ada.Command_Line. However, these arguments can also

--  be read from a list of strings. This can be useful in several contexts,

--  either because your system does not support Ada.Command_Line, or because

--  you are manipulating other tools and creating their command lines by hand,

--  or for any other reason.

--  To create the list of strings, it is recommended to use

--  GNAT.OS_Lib.Argument_String_To_List.

--  The example below shows how to get the parameters from such a list. Note

--  also the use of '*' to get all the switches, and not report errors when an

--  unexpected switch was used by the user

--  declare

--     Parser : Opt_Parser;

--     Args : constant Argument_List_Access :=

--        GNAT.OS_Lib.Argument_String_To_List ("-g -O1 -Ipath");

--  begin

--     Initialize_Option_Scan (Parser, Args);

--     while Getopt ("* g O! I=", Parser) /= ASCII.NUL loop

--        Put_Line ("Switch " & Full_Switch (Parser)

--                  & " param=" & Parameter (Parser));

--     end loop;

--     Free (Parser);

--  end;

-------------------------------------------

-- High-Level Command Line Configuration --

-------------------------------------------

--  As shown above, the code is still relatively low-level. For instance, there

--  is no way to indicate which switches are related (thus if "-l" and "--long"

--  should have the same effect, your code will need to test for both cases).

--  Likewise, it is difficult to handle more advanced constructs, like:

--    * Specifying -gnatwa is the same as specifying -gnatwu -gnatwv, but

--      shorter and more readable

--    * All switches starting with -gnatw can be grouped, for instance one

--      can write -gnatwcd instead of -gnatwc -gnatwd.

--      Of course, this can be combined with the above and -gnatwacd is the

--      same as -gnatwc -gnatwd -gnatwu -gnatwv

--    * The switch -T is the same as -gnatwAB (same as -gnatwA -gnatwB)

--  With the above form of Getopt, you would receive "-gnatwa", "-T" or

--  "-gnatwcd" in the examples above, and thus you require additional manual

--  parsing of the switch.

--  Instead, this package provides the type Command_Line_Configuration, which

--  stores all the knowledge above. For instance:

--     Config : Command_Line_Configuration;

--     Define_Alias  (Config, "-gnatwa", "-gnatwu -gnatwv");

--     Define_Prefix (Config, "-gnatw");

--     Define_Alias  (Config, "-T",      "-gnatwAB");

--  You then need to specify all possible switches in your application by

--  calling Define_Switch, for instance:

--     Define_Switch (Config, "-gnatwu", Help => "warn on unused entities");

--     Define_Switch (Config, "-gnatwv", Help => "warn on unassigned var");

--     ...

--  Specifying the help message is optional, but makes it easy to then call

--  the function

--     Display_Help (Config);

--  that will display a properly formatted help message for your application,

--  listing all possible switches. That way you have a single place in which

--  to maintain the list of switches and their meaning, rather than maintaining

--  both the string to pass to Getopt and a subprogram to display the help.

--  Both will properly stay synchronized.

--  Once you have this Config, you just have to call

--     Getopt (Config, Callback'Access);

--  to parse the command line. The Callback will be called for each switch

--  found on the command line (in the case of our example, that is "-gnatwu"

--  and then "-gnatwv", not "-gnatwa" itself). This simplifies command line

--  parsing a lot.

--  In fact, this can be further automated for the most command case where the

--  parameter passed to a switch is stored in a variable in the application.

--  When a switch is defined, you only have to indicate where to store the

--  value, and let Getopt do the rest. For instance:

--     Optimization : aliased Integer;

--     Verbose      : aliased Boolean;

--

--     Define_Switch (Config, Verbose'Access,

--                    "-v", Long_Switch => "--verbose",

--                    Help => "Output extra verbose information");

--     Define_Switch (Config, Optimization'Access,

--                    "-O?", Help => "Optimization level");

--

--     Getopt (Config);  --  No callback

--  Since all switches are handled automatically, we don't even need to pass

--  a callback to Getopt. Once getopt has been called, the two variables

--  Optimization and Verbose have been properly initialized, either to the

--  default value or to the value found on the command line.

------------------------------------------------

-- Creating and Manipulating the Command Line --

------------------------------------------------

--  This package provides mechanisms to create and modify command lines by

--  adding or removing arguments from them. The resulting command line is kept

--  as short as possible by coalescing arguments whenever possible.

--  Complex command lines can thus be constructed, for example from a GUI

--  (although this package does not by itself depend upon any specific GUI

--  toolkit).

--  Using the configuration defined earlier, one can then construct a command

--  line for the tool with:

--     Cmd : Command_Line;

--     Set_Configuration (Cmd, Config);   --  Config created earlier

--     Add_Switch (Cmd, "-bar");

--     Add_Switch (Cmd, "-gnatwu");

--     Add_Switch (Cmd, "-gnatwv");  --  will be grouped with the above

--     Add_Switch (Cmd, "-T");

--  The resulting command line can be iterated over to get all its switches,

--  There are two modes for this iteration: either you want to get the

--  shortest possible command line, which would be:

--      -bar -gnatwaAB

--  or on the other hand you want each individual switch (so that your own

--  tool does not have to do further complex processing), which would be:

--      -bar -gnatwu -gnatwv -gnatwA -gnatwB

--  Of course, we can assume that the tool you want to spawn would understand

--  both of these, since they are both compatible with the description we gave

--  above. However, the first result is useful if you want to show the user

--  what you are spawning (since that keeps the output shorter), and the second

--  output is more useful for a tool that would check whether -gnatwu was

--  passed (which isn't obvious in the first output). Likewise, the second

--  output is more useful if you have a graphical interface since each switch

--  can be associated with a widget, and you immediately know whether -gnatwu

--  was selected.

--

--  Some command line arguments can have parameters, which on a command line

--  appear as a separate argument that must immediately follow the switch.

--  Since the subprograms in this package will reorganize the switches to group

--  them, you need to indicate what is a command line

--  parameter, and what is a switch argument.

--  This is done by passing an extra argument to Add_Switch, as in:

--     Add_Switch (Cmd, "-foo", Parameter => "arg1");

--  This ensures that "arg1" will always be treated as the argument to -foo,

--  and will not be grouped with other parts of the command line.

with Ada.Command_Line;

with GNAT.Directory_Operations;

with GNAT.OS_Lib;

with GNAT.Regexp;

with GNAT.Strings;

package GNAT.Command_Line is

   -------------

   -- Parsing --

   -------------

   type Opt_Parser is private;

   Command_Line_Parser : constant Opt_Parser;

   --  This object is responsible for parsing a list of arguments, which by

   --  default are the standard command line arguments from Ada.Command_Line.

   --  This is really a pointer to actual data, which must therefore be

   --  initialized through a call to Initialize_Option_Scan, and must be freed

   --  with a call to Free.

   --

   --  As a special case, Command_Line_Parser does not need to be either

   --  initialized or free-ed.

   procedure Initialize_Option_Scan

     (Switch_Char              : Character := '-';

      Stop_At_First_Non_Switch : Boolean := False;

      Section_Delimiters       : String := "");

   procedure Initialize_Option_Scan

     (Parser                   : out Opt_Parser;

      Command_Line             : GNAT.OS_Lib.Argument_List_Access;

      Switch_Char              : Character := '-';

      Stop_At_First_Non_Switch : Boolean := False;

      Section_Delimiters       : String := "");

   --  The first procedure resets the internal state of the package to prepare

   --  to rescan the parameters. It does not need to be called before the first

   --  use of Getopt (but it could be), but it must be called if you want to

   --  start rescanning the command line parameters from the start. The

   --  optional parameter Switch_Char can be used to reset the switch

   --  character, e.g. to '/' for use in DOS-like systems.

   --

   --  The second subprogram initializes a parser that takes its arguments from

   --  an array of strings rather than directly from the command line. In this

   --  case, the parser is responsible for freeing the strings stored in

   --  Command_Line. If you pass null to Command_Line, this will in fact create

   --  a second parser for Ada.Command_Line, which doesn't share any data with

   --  the default parser. This parser must be free-ed.

   --

   --  The optional parameter Stop_At_First_Non_Switch indicates if Getopt is

   --  to look for switches on the whole command line, or if it has to stop as

   --  soon as a non-switch argument is found.

   --

   --  Example:

   --

   --      Arguments: my_application file1 -c

   --

   --      If Stop_At_First_Non_Switch is False, then -c will be considered

   --      as a switch (returned by getopt), otherwise it will be considered

   --      as a normal argument (returned by Get_Argument).

   --

   --  If Section_Delimiters is set, then every following subprogram

   --  (Getopt and Get_Argument) will only operate within a section, which

   --  is delimited by any of these delimiters or the end of the command line.

   --

   --  Example:

   --      Initialize_Option_Scan (Section_Delimiters => "largs bargs cargs");

   --

   --      Arguments on command line : my_application -c -bargs -d -e -largs -f

   --      This line contains three sections, the first one is the default one

   --      and includes only the '-c' switch, the second one is between -bargs

   --      and -largs and includes '-d -e' and the last one includes '-f'.

   procedure Free (Parser : in out Opt_Parser);

   --  Free the memory used by the parser. Calling this is not mandatory for

   --  the Command_Line_Parser

   procedure Goto_Section

     (Name   : String := "";

      Parser : Opt_Parser := Command_Line_Parser);

   --  Change the current section. The next Getopt or Get_Argument will start

   --  looking at the beginning of the section. An empty name ("") refers to

   --  the first section between the program name and the first section

   --  delimiter. If the section does not exist in Section_Delimiters, then

   --  Invalid_Section is raised. If the section does not appear on the command

   --  line, then it is treated as an empty section.

   function Full_Switch

     (Parser : Opt_Parser := Command_Line_Parser) return String;

   --  Returns the full name of the last switch found (Getopt only returns the

   --  first character). Does not include the Switch_Char ('-' by default),

   --  unless the "*" option of Getopt is used (see below).

   function Current_Section

     (Parser : Opt_Parser := Command_Line_Parser) return String;

   --  Return the name of the current section.

   --  The list of valid sections is defined through Initialize_Option_Scan

   function Getopt

     (Switches    : String;

      Concatenate : Boolean := True;

      Parser      : Opt_Parser := Command_Line_Parser) return Character;

   --  This function moves to the next switch on the command line (defined as

   --  switch character followed by a character within Switches, casing being

   --  significant). The result returned is the first character of the switch

   --  that is located. If there are no more switches in the current section,

   --  returns ASCII.NUL. If Concatenate is True (the default), the switches do

   --  not need to be separated by spaces (they can be concatenated if they do

   --  not require an argument, e.g. -ab is the same as two separate arguments

   --  -a -b).

   --

   --  Switches is a string of all the possible switches, separated by

   --  spaces. A switch can be followed by one of the following characters:

   --

   --   ':'  The switch requires a parameter. There can optionally be a space

   --        on the command line between the switch and its parameter.

   --

   --   '='  The switch requires a parameter. There can either be a '=' or a

   --        space on the command line between the switch and its parameter.

   --

   --   '!'  The switch requires a parameter, but there can be no space on the

   --        command line between the switch and its parameter.

   --

   --   '?'  The switch may have an optional parameter. There can be no space

   --        between the switch and its argument.

   --

   --        e.g. if Switches has the following value : "a? b",

   --        The command line can be:

   --

   --             -afoo    :  -a switch with 'foo' parameter

   --             -a foo   :  -a switch and another element on the

   --                           command line 'foo', returned by Get_Argument

   --

   --     Example: if Switches is "-a: -aO:", you can have the following

   --              command lines:

   --

   --                -aarg    :  'a' switch with 'arg' parameter

   --                -a arg   :  'a' switch with 'arg' parameter

   --                -aOarg   :  'aO' switch with 'arg' parameter

   --                -aO arg  :  'aO' switch with 'arg' parameter

   --

   --    Example:

   --

   --       Getopt ("a b: ac ad?")

   --

   --         accept either 'a' or 'ac' with no argument,

   --         accept 'b' with a required argument

   --         accept 'ad' with an optional argument

   --

   --  If the first item in switches is '*', then Getopt will catch

   --  every element on the command line that was not caught by any other

   --  switch. The character returned by GetOpt is '*', but Full_Switch

   --  contains the full command line argument, including leading '-' if there

   --  is one. If this character was not returned, there would be no way of

   --  knowing whether it is there or not.

   --

   --    Example

   --       Getopt ("* a b")

   --       If the command line is '-a -c toto.o -b', Getopt will return

   --       successively 'a', '*', '*' and 'b', with Full_Switch returning

   --       "a", "-c", "toto.o", and "b".

   --

   --  When Getopt encounters an invalid switch, it raises the exception

   --  Invalid_Switch and sets Full_Switch to return the invalid switch.

   --  When Getopt cannot find the parameter associated with a switch, it

   --  raises Invalid_Parameter, and sets Full_Switch to return the invalid

   --  switch.

   --

   --  Note: in case of ambiguity, e.g. switches a ab abc, then the longest

   --  matching switch is returned.

   --

   --  Arbitrary characters are allowed for switches, although it is

   --  strongly recommended to use only letters and digits for portability

   --  reasons.

   --

   --  When Concatenate is False, individual switches need to be separated by

   --  spaces.

   --

   --    Example

   --       Getopt ("a b", Concatenate => False)

   --       If the command line is '-ab', exception Invalid_Switch will be

   --       raised and Full_Switch will return "ab".

   function Get_Argument

     (Do_Expansion : Boolean := False;

      Parser       : Opt_Parser := Command_Line_Parser) return String;

   --  Returns the next element on the command line that is not a switch.  This

   --  function should not be called before Getopt has returned ASCII.NUL.

   --

   --  If Do_Expansion is True, then the parameter on the command line will

   --  be considered as a filename with wild cards, and will be expanded. The

   --  matching file names will be returned one at a time. This is useful in

   --  non-Unix systems for obtaining normal expansion of wild card references.

   --  When there are no more arguments on the command line, this function

   --  returns an empty string.

   function Parameter

     (Parser : Opt_Parser := Command_Line_Parser) return String;

   --  Returns parameter associated with the last switch returned by Getopt.

   --  If no parameter was associated with the last switch, or no previous call

   --  has been made to Get_Argument, raises Invalid_Parameter. If the last

   --  switch was associated with an optional argument and this argument was

   --  not found on the command line, Parameter returns an empty string.

   function Separator

     (Parser : Opt_Parser := Command_Line_Parser) return Character;

   --  The separator that was between the switch and its parameter. This is

   --  useful if you want to know exactly what was on the command line. This

   --  is in general a single character, set to ASCII.NUL if the switch and

   --  the parameter were concatenated. A space is returned if the switch and

   --  its argument were in two separate arguments.

   Invalid_Section : exception;

   --  Raised when an invalid section is selected by Goto_Section

   Invalid_Switch : exception;

   --  Raised when an invalid switch is detected in the command line

   Invalid_Parameter : exception;

   --  Raised when a parameter is missing, or an attempt is made to obtain a

   --  parameter for a switch that does not allow a parameter.

   -----------------------------------------

   -- Expansion of command line arguments --

   -----------------------------------------

   --  These subprograms take care of of expanding globbing patterns on the

   --  command line. On Unix, such expansion is done by the shell before your

   --  application is called. But on Windows you must do this expansion

   --  yourself.

   type Expansion_Iterator is limited private;

   --  Type used during expansion of file names

   procedure Start_Expansion

     (Iterator     : out Expansion_Iterator;

      Pattern      : String;

      Directory    : String := "";

      Basic_Regexp : Boolean := True);

   --  Initialize a wild card expansion. The next calls to Expansion will

   --  return the next file name in Directory which match Pattern (Pattern

   --  is a regular expression, using only the Unix shell and DOS syntax if

   --  Basic_Regexp is True). When Directory is an empty string, the current

   --  directory is searched.

   --

   --  Pattern may contain directory separators (as in "src/*/*.ada").

   --  Subdirectories of Directory will also be searched, up to one

   --  hundred levels deep.

   --

   --  When Start_Expansion has been called, function Expansion should

   --  be called repeatedly until it returns an empty string, before

   --  Start_Expansion can be called again with the same Expansion_Iterator

   --  variable.

   function Expansion (Iterator : Expansion_Iterator) return String;

   --  Returns the next file in the directory matching the parameters given

   --  to Start_Expansion and updates Iterator to point to the next entry.

   --  Returns an empty string when there are no more files.

   --

   --  If Expansion is called again after an empty string has been returned,

   --  then the exception GNAT.Directory_Operations.Directory_Error is raised.

   -----------------

   -- Configuring --

   -----------------

   --  The following subprograms are used to manipulate a command line

   --  represented as a string (for instance "-g -O2"), as well as parsing

   --  the switches from such a string. They provide high-level configurations

   --  to define aliases (a switch is equivalent to one or more other switches)

   --  or grouping of switches ("-gnatyac" is equivalent to "-gnatya" and

   --  "-gnatyc").

   --  See the top of this file for examples on how to use these subprograms

   type Command_Line_Configuration is private;

   procedure Define_Section

     (Config  : in out Command_Line_Configuration;

      Section : String);

   --  Indicates a new switch section. All switches belonging to the same

   --  section are ordered together, preceded by the section. They are placed

   --  at the end of the command line (as in "gnatmake somefile.adb -cargs -g")

   --

   --  The section name should not include the leading '-'. So for instance in

   --  the case of gnatmake we would use:

   --

   --      Define_Section (Config, "cargs");

   --      Define_Section (Config, "bargs");

   procedure Define_Alias

     (Config   : in out Command_Line_Configuration;

      Switch   : String;

      Expanded : String;

      Section  : String := "");

   --  Indicates that whenever Switch appears on the command line, it should

   --  be expanded as Expanded. For instance, for the GNAT compiler switches,

   --  we would define "-gnatwa" as an alias for "-gnatwcfijkmopruvz", ie some

   --  default warnings to be activated.

   --

   --  This expansion is only done within the specified section, which must

   --  have been defined first through a call to [Define_Section].

   procedure Define_Prefix

     (Config : in out Command_Line_Configuration;

      Prefix : String);

   --  Indicates that all switches starting with the given prefix should be

   --  grouped. For instance, for the GNAT compiler we would define "-gnatw" as

   --  a prefix, so that "-gnatwu -gnatwv" can be grouped into "-gnatwuv" It is

   --  assumed that the remainder of the switch ("uv") is a set of characters

   --  whose order is irrelevant. In fact, this package will sort them

   --  alphabetically.

   --

   --  When grouping switches that accept arguments (for instance "-gnatyL!"

   --  as the definition, and "-gnatyaL12b" as the command line), only

   --  numerical arguments are accepted. The above is equivalent to

   --  "-gnatya -gnatyL12 -gnatyb".

   procedure Define_Switch

     (Config      : in out Command_Line_Configuration;

      Switch      : String := "";

      Long_Switch : String := "";

      Help        : String := "";

      Section     : String := "");

   --  Indicates a new switch. The format of this switch follows the getopt

   --  format (trailing ':', '?', etc for defining a switch with parameters).

   --

   --  Switch should also start with the leading '-' (or any other characters).

   --  If this character is not '-', you need to call Initialize_Option_Scan to

   --  set the proper character for the parser.

   --

   --  The switches defined in the command_line_configuration object are used

   --  when ungrouping switches with more that one character after the prefix.

   --

   --  Switch and Long_Switch (when specified) are aliases and can be used

   --  interchangeably. There is no check that they both take an argument or

   --  both take no argument.

   --  Switch can be set to "*" to indicate that any switch is supported (in

   --  which case Getopt will return '*', see its documentation).

   --

   --  Help is used by the Display_Help procedure to describe the supported

   --  switches.

   --

   --  In_Section indicates in which section the switch is valid (you need to

   --  first define the section through a call to Define_Section).

   procedure Define_Switch

     (Config      : in out Command_Line_Configuration;

      Output      : access Boolean;

      Switch      : String := "";

      Long_Switch : String := "";

      Help        : String := "";

      Section     : String := "";

      Value       : Boolean := True);

   --  See Define_Switch for a description of the parameters.

   --  When the switch is found on the command line, Getopt will set

   --  Output.all to Value.

   --  Output is always initially set to "not Value", so that if the switch is

   --  not found on the command line, Output still has a valid value.

   --  The switch must not take any parameter.

   --  Output must exist at least as long as Config, otherwise erroneous memory

   --  access may happen.

   procedure Define_Switch

     (Config      : in out Command_Line_Configuration;

      Output      : access Integer;

      Switch      : String := "";

      Long_Switch : String := "";

      Help        : String := "";

      Section     : String := "";

      Initial     : Integer := 0;

      Default     : Integer := 1);

   --  See Define_Switch for a description of the parameters.

   --  When the switch is found on the command line, Getopt will set

   --  Output.all to the value of the switch's parameter. If the parameter is

   --  not an integer, Invalid_Parameter is raised.

   --  Output is always initialized to Initial. If the switch has an optional

   --  argument which isn't specified by the user, then Output will be set to

   --  Default.

   procedure Define_Switch

     (Config      : in out Command_Line_Configuration;

      Output      : access GNAT.Strings.String_Access;

      Switch      : String := "";

      Long_Switch : String := "";

      Help        : String := "";

      Section     : String := "");

   --  Set Output to the value of the switch's parameter when the switch is

   --  found on the command line.

   --  Output is always initialized to the empty string.

   procedure Set_Usage

     (Config   : in out Command_Line_Configuration;

      Usage    : String := "[switches] [arguments]";

      Help     : String := "";

      Help_Msg : String := "");

   --  Defines the general format of the call to the application, and a short

   --  help text. These are both displayed by Display_Help. When a non-empty

   --  Help_Msg is given, it is used by Display_Help instead of the

   --  automatically generated list of supported switches.

   procedure Display_Help (Config : Command_Line_Configuration);

   --  Display the help for the tool (ie its usage, and its supported switches)

   function Get_Switches

     (Config      : Command_Line_Configuration;

      Switch_Char : Character := '-';

      Section     : String := "") return String;

   --  Get the switches list as expected by Getopt, for a specific section of

   --  the command line. This list is built using all switches defined

   --  previously via Define_Switch above.

   function Section_Delimiters

     (Config : Command_Line_Configuration) return String;

   --  Return a string suitable for use in Initialize_Option_Scan

   procedure Free (Config : in out Command_Line_Configuration);

   --  Free the memory used by Config

   type Switch_Handler is access procedure

     (Switch    : String;

      Parameter : String;

      Section   : String);

   --  Called when a switch is found on the command line.

   --  [Switch] includes any leading '-' that was specified in Define_Switch.

   --  This is slightly different from the functional version of Getopt above,

   --  for which Full_Switch omits the first leading '-'.

   Exit_From_Command_Line : exception;

   --  Emitted when the program should exit.

   --  This is called when Getopt below has seen -h, --help or an invalid

   --  switch.

   procedure Getopt

     (Config      : Command_Line_Configuration;

      Callback    : Switch_Handler := null;

      Parser      : Opt_Parser := Command_Line_Parser;

      Concatenate : Boolean := True);

   --  Similar to the standard Getopt function. For each switch found on the

   --  command line, this calls Callback, if the switch is not handled

   --  automatically.

   --

   --  The list of valid switches are the ones from the configuration. The

   --  switches that were declared through Define_Switch with an Output

   --  parameter are never returned (and result in a modification of the Output

   --  variable). This function will in fact never call [Callback] if all

   --  switches were handled automatically and there is nothing left to do.

   --

   --  The option Concatenate is identical to the one of the standard Getopt

   --  function.

   --

   --  This procedure automatically adds -h and --help to the valid switches,

   --  to display the help message and raises Exit_From_Command_Line.

   --  If an invalid switch is specified on the command line, this procedure

   --  will display an error message and raises Invalid_Switch again.

   --

   --  This function automatically expands switches:

   --

   --    If Define_Prefix was called (for instance "-gnaty") and the user

   --    specifies "-gnatycb" on the command line, then Getopt returns

   --    "-gnatyc" and "-gnatyb" separately.

   --

   --    If Define_Alias was called (for instance "-gnatya = -gnatycb") then

   --    the latter is returned (in this case it also expands -gnaty as per

   --    the above.

   --

   --  The goal is to make handling as easy as possible by leaving as much

   --  work as possible to this package.

   --

   --  As opposed to the standard Getopt, this one will analyze all sections

   --  as defined by Define_Section, and automatically jump from one section to

   --  the next.

   ------------------------------

   -- Generating command lines --

   ------------------------------

   --  Once the command line configuration has been created, you can build your

   --  own command line. This will be done in general because you need to spawn

   --  external tools from your application.

   --  Although it could be done by concatenating strings, the following

   --  subprograms will properly take care of grouping switches when possible,

   --  so as to keep the command line as short as possible. They also provide a

   --  way to remove a switch from an existing command line.

   --  For instance:

   --      declare

   --         Config : Command_Line_Configuration;

   --         Line : Command_Line;

   --         Args : Argument_List_Access;

   --      begin

   --         Define_Switch (Config, "-gnatyc");

   --         Define_Switch (Config, ...);  --  for all valid switches

   --         Define_Prefix (Config, "-gnaty");

   --         Set_Configuration (Line, Config);

   --         Add_Switch (Line, "-O2");

   --         Add_Switch (Line, "-gnatyc");

   --         Add_Switch (Line, "-gnatyd");

   --

   --         Build (Line, Args);

   --         --   Args is now  ["-O2", "-gnatycd"]

   --      end;

   type Command_Line is private;

   procedure Set_Configuration

     (Cmd    : in out Command_Line;

      Config : Command_Line_Configuration);

   function Get_Configuration

     (Cmd : Command_Line) return Command_Line_Configuration;

   --  Set or retrieve the configuration used for that command line. The Config

   --  must have been initialized first, by calling one of the Define_Switches

   --  subprograms.

   procedure Set_Command_Line

     (Cmd                : in out Command_Line;

      Switches           : String;

      Getopt_Description : String    := "";

      Switch_Char        : Character := '-');

   --  Set the new content of the command line, by replacing the current

   --  version with Switches.

   --

   --  The parsing of Switches is done through calls to Getopt, by passing

   --  Getopt_Description as an argument. (A "*" is automatically prepended so

   --  that all switches and command line arguments are accepted). If a config

   --  was defined via Set_Configuration, the Getopt_Description parameter will

   --  be ignored.

   --

   --  To properly handle switches that take parameters, you should document

   --  them in Getopt_Description. Otherwise, the switch and its parameter will

   --  be recorded as two separate command line arguments as returned by a

   --  Command_Line_Iterator (which might be fine depending on your

   --  application).

   --

   --  If the command line has sections (such as -bargs -cargs), then they

   --  should be listed in the Sections parameter (as "-bargs -cargs").

   --

   --  This function can be used to reset Cmd by passing an empty string.

   --

   --  If an invalid switch is found on the command line (ie wasn't defined in

   --  the configuration via Define_Switch), and the configuration wasn't set

   --  to accept all switches (by defining "*" as a valid switch), then an

   --  exception Invalid_Switch is raised. The exception message indicates the

   --  invalid switch.

   procedure Add_Switch

     (Cmd        : in out Command_Line;