OpenE2K
/
gcc
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

g-comlin.ads, [...] (Command_Line_Configuration, [...]): New types 

2007-09-26  Emmanuel Briot  <briot@adacore.com>

	* g-comlin.ads, g-comlin.adb (Command_Line_Configuration,
	Command_Line): New types
	(Define_Alias, Define_Prefix, Free): New subprograms. These provide
	support for defining how switches can be grouped on a command line (as
	is the case for -gnatw... for GNAT), and how simple switches can be
	used as aliases for more complex switches (-gnatwa is same as
	-gnatwbcef...)
	(Set_Command_Line, Add_Switch, Remove_Switch): New subprogram
	(Start, Current_*): New subprograms
	Added support for parsing an array of strings in addition to the real
	command line.
	(Opt_Parser, Opt_Parser_Data): New type. As a result, some types had to
	 be moved from the body to the private part of the spec.
	(*): All subprograms now have an extra parameter with default value to
	specify which parser should be used. For backward compatibility, it
	defaults to parsing the command line of the application. They were also
	modified to properly handle cases where each of the argument does not
	start at index 1 (which is always true for Ada.Command_Line, but not
	when processing any Argument_List).
	(Free): New subprogram
	(Internal_Initialize_Option_Scan, Find_Longuest_Matching_Switch,
	Argument): New subprograms
	(Switch_Parameter_Type): New enum, which clarifies the code. The extra
	special characters like ':', '=',... are now handled in a single place,
	which makes the code more extensible eventually.
	(Getopt, Full_Switch): When the switch was returned as part of the
	special character '*', make sure it is prepended by the switch character
	('-' in general), so that the application knows whether "foo" or "-foo"
	was specified on the command line.

From-SVN: r128791
This commit is contained in:
Emmanuel Briot 2007-09-26 12:44:07 +02:00 committed by Arnaud Charlet
parent dd05ba2754
commit da2ac8c26f
2 changed files with 1742 additions and 413 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1660
gcc/ada/g-comlin.adb
View File

File diff suppressed because it is too large Load Diff

495
gcc/ada/g-comlin.ads
View File

@ -31,10 +31,21 @@
-- --
------------------------------------------------------------------------------
-- High level package for command line parsing
-- High level package for command line parsing and manipulation
-- This package provides an interface to Ada.Command_Line, to do the
-- parsing of command line arguments. Here is a small usage example:
-- Parsing 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.
-- This package is flexible enough to accomodate various needs: optional
-- switch parameters, various characters to separate a switch and its
-- parameter, whether to stop the parsing at the first non-switch argument
-- encountered, etc.
-- begin
-- loop
@ -50,7 +61,7 @@
-- when 'b' =>
-- Put_Line ("Got b + " & Parameter);
--
-- when others =>
-- raise Program_Error; -- cannot occur!
-- end case;
@ -64,16 +75,17 @@
-- 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;
-- A more complicated example would involve the use of sections for the
-- switches, as for instance in gnatmake. These sections are separated by
-- special switches chosen by the programer. Each section acts as a
-- command line of its own.
-- 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, chosen by the programer.
-- Each section acts as a command line of its own.
-- begin
-- Initialize_Option_Scan ('-', False, "largs bargs cargs");
@ -84,34 +96,198 @@
-- Goto_Section ("bargs");
-- loop
-- -- Same loop as above to get switches and arguments
-- -- The supports switches in Get_Opt might be different
-- -- The supported switches in Get_Opt might be different
-- end loop;
-- Goto_Section ("cargs");
-- loop
-- -- Same loop as above to get switches and arguments
-- -- The supports switches in Get_Opt might be different
-- -- The supported switches in Get_Opt might be different
-- end loop;
-- end;
-- The example above have shown 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 line 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 Get_Opt ("* g O! I=", Parser) /= ASCII.NUL loop
-- Put_Line ("Switch " & Full_Switch (Parser)
-- & " param=" & Parameter (Parser));
-- end loop;
-- Free (Parser);
-- end;
--
-- Creating and manipulating the command line
-- ===========================================
-- This package provides handling of command line by providing methods to
-- add or remove arguments from it. The resulting command line is kept as
-- short as possible by coalescing arguments whenever possible.
-- This package can be used to construct complex command lines for instance
-- from an GUI interface (although the package itself does not depend on a
-- specific GUI toolkit). For instance, if you are configuring the command
-- line to use when spawning a tool with the following characteristics:
-- * 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
-- * A switch -foo takes one mandatory parameter
-- These attributes can be configured through this package with the following
-- calls:
-- Config : Command_Line_Configuration;
-- Define_Prefix (Config, "-gnatw");
-- Define_Alias (Config, "-gnatwa", "-gnatwuv");
-- Define_Alias (Config, "-T", "-gnatwAB");
-- Using this configuration, one can then construct a command line for the
-- tool with:
-- Cmd : Command_Line;
-- Set_Configuration (Cmd, Config);
-- 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", "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.
-- Parsing the command line with grouped arguments
-- ===============================================
-- This package also works great in collaboration with GNAT.Command_Line, to
-- parse the input to your tools. If you are writing the tool we described
-- above, you would do a first loop with Getopt to pass the switches and
-- their arguments, and create a temporary representation of the command line
-- as a Command_Line object. Finally, you can ask each individual switch to
-- that object. For instance:
-- declare
-- Cmd : Command_Line;
-- Iter : Command_Line_Iterator;
-- begin
-- while Getopt ("foo: gnatw! T bar") /= ASCII.NUL loop
-- Add_Switch (Cmd, Full_Switch, Parameter);
-- end loop;
-- Start (Cmd, Iter, Expanded => True);
-- while Has_More (Iter) loop
-- if Current_Switch (Iter) = "-gnatwu" then ..
-- elsif Current_Switch (Iter) = "-gnatwv" then ...
-- end if;
-- Next (Iter);
-- end loop;
-- The above means that your tool does not have to handle on its own whether
-- the user passed -gnatwa (in which case -gnatwu was indeed selected), or
-- just -gnatwu, or a combination of -gnatw switches as in -gnatwuv.
with Ada.Command_Line;
with GNAT.Directory_Operations;
with GNAT.OS_Lib;
with GNAT.Regexp;
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 := "");
-- This 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
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 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.
-- 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:
--
@ -126,27 +302,35 @@ package GNAT.Command_Line is
-- is delimited by any of these delimiters or the end of the command line.
--
-- Example:
-- Initialize_Option_Scan ("largs bargs cargs");
-- Initialize_Option_Scan (Section_Delimiters => "largs bargs cargs");
--
-- Arguments on command line : my_application -c -bargs -d -e -largs -f
-- This line is made of three section, 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 Goto_Section (Name : String := "");
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 of 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, then Invalid_Section is
-- raised.
function Full_Switch return String;
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)
function Getopt
(Switches : String;
Concatenate : Boolean := True) return Character;
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
@ -196,7 +380,10 @@ package GNAT.Command_Line is
--
-- 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 '*'
-- 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")
@ -204,7 +391,6 @@ package GNAT.Command_Line is
-- successively 'a', '*', '*' and 'b'. When '*' is returned,
-- Full_Switch returns the corresponding item on the command line.
--
--
-- 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
@ -226,7 +412,9 @@ package GNAT.Command_Line is
-- 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) return String;
function Get_Argument
(Do_Expansion : Boolean := False;
Parser : Opt_Parser := Command_Line_Parser) return String;
-- Returns the next element on the command line which is not a switch.
-- This function should not be called before Getopt has returned
-- ASCII.NUL.
@ -238,7 +426,8 @@ package GNAT.Command_Line is
-- string. This is useful in non-Unix systems for obtaining normal
-- expansion of wild card references.
function Parameter return String;
function Parameter
(Parser : Opt_Parser := Command_Line_Parser) return String;
-- Returns the 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.
@ -246,6 +435,14 @@ package GNAT.Command_Line is
-- 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
-- of little use in general, only 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.
type Expansion_Iterator is limited private;
-- Type used during expansion of file names
@ -288,6 +485,154 @@ package GNAT.Command_Line is
-- Raised when a parameter is missing, or an attempt is made to obtain a
-- parameter for a switch that does not allow a parameter
-----------------
-- Configuring --
-----------------
type Command_Line_Configuration is private;
procedure Define_Alias
(Config : in out Command_Line_Configuration;
Switch : String;
Expanded : 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.
--
-- Likewise, in some context you could define "--verbose" as an alias for
-- ("-v", "--full"), ie two switches.
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 assume that the remaining of the switch ("uv") is a set of
-- characters whose order is irrelevant. In fact, this package will sort
-- them alphabetically.
procedure Free (Config : in out Command_Line_Configuration);
-- Free the memory used by Config
-------------
-- Editing --
-------------
type Command_Line is private;
procedure Set_Configuration
(Cmd : in out Command_Line;
Config : Command_Line_Configuration);
-- Set the configuration for this command line
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).
--
-- 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).
--
-- This function can be used to reset Cmd by passing an empty string.
procedure Add_Switch
(Cmd : in out Command_Line;
Switch : String;
Parameter : String := "";
Separator : Character := ' ');
-- Add a new switch to the command line, and combine/group it with existing
-- switches if possible. Nothing is done if the switch already exists with
-- the same parameter.
--
-- If the Switch takes a parameter, the latter should be specified
-- separately, so that the association between the two is always correctly
-- recognized even if the order of switches on the command line changes.
-- For instance, you should pass "--check=full" as ("--check", "full") so
-- that Remove_Switch below can simply take "--check" in parameter. That
-- will automatically remove "full" as well. The value of the parameter is
-- never modified by this package.
--
-- On the other hand, you could decide to simply pass "--check=full" as
-- the Switch above, and then pass no parameter. This means that you need
-- to pass "--check=full" to Remove_Switch as well.
--
-- A Switch with a parameter will never be grouped with another switch to
-- avoid ambiguities as to who the parameter applies to.
--
-- Separator is the character that goes between the switches and its
-- parameter on the command line. If it is set to ASCII.NUL, then no
-- separator is applied, and they are concatenated
procedure Remove_Switch
(Cmd : in out Command_Line;
Switch : String;
Remove_All : Boolean := False);
-- Remove Switch from the command line, and ungroup existing switches if
-- necessary.
--
-- The actual parameter to the switches are ignored. If for instance
-- you are removing "-foo", then "-foo param1" and "-foo param2" can
-- be removed.
--
-- If Remove_All is True, then all matching switches are removed, otherwise
-- only the first matching one is removed.
procedure Remove_Switch
(Cmd : in out Command_Line;
Switch : String;
Parameter : String);
-- Remove a switch with a specific parameter. If Parameter is the empty
-- string, then only a switch with no parameter will be removed.
---------------
-- Iterating --
---------------
type Command_Line_Iterator is private;
procedure Start
(Cmd : in out Command_Line;
Iter : in out Command_Line_Iterator;
Expanded : Boolean);
-- Start iterating over the command line arguments. If Expanded is true,
-- then the arguments are not grouped and no alias is used. For instance,
-- "-gnatwv" and "-gnatwu" would be returned instead of "-gnatwuv".
--
-- The iterator becomes invalid if the command line is changed through a
-- call to Add_Switch, Remove_Switch or Set_Command_Line.
function Current_Switch (Iter : Command_Line_Iterator) return String;
function Current_Separator (Iter : Command_Line_Iterator) return String;
function Current_Parameter (Iter : Command_Line_Iterator) return String;
-- Return the current switch and its parameter (or the empty string if
-- there is no parameter or the switch was added through Add_Switch
-- without specifying the parameter.
--
-- Separator is the string that goes between the switch and its separator.
-- It could be the empty string if they should be concatenated, or a space
-- for instance. When printing, you should not add any other character.
function Has_More (Iter : Command_Line_Iterator) return Boolean;
-- Return True if there are more switches to be returned
procedure Next (Iter : in out Command_Line_Iterator);
-- Move to the next switch
procedure Free (Cmd : in out Command_Line);
-- Free the memory used by Cmd
private
Max_Depth : constant := 100;
@ -305,6 +650,22 @@ private
type Level_Array is array (Depth) of Level;
type Section_Number is new Natural range 0 .. 65534;
for Section_Number'Size use 16;
type Parameter_Type is record
Arg_Num : Positive;
First : Positive;
Last : Positive;
Extra : Character;
end record;
type Is_Switch_Type is array (Natural range <>) of Boolean;
pragma Pack (Is_Switch_Type);
type Section_Type is array (Natural range <>) of Section_Number;
pragma Pack (Section_Type);
type Expansion_Iterator is limited record
Start : Positive := 1;
-- Position of the first character of the relative path to check against
@ -324,4 +685,86 @@ private
-- separators in the pattern.
end record;
type Opt_Parser_Data (Arg_Count : Natural) is record
Arguments : GNAT.OS_Lib.Argument_List_Access;
-- null if reading from the command line
The_Parameter : Parameter_Type;
The_Separator : Character;
The_Switch : Parameter_Type;
-- This type and this variable are provided to store the current switch
-- and parameter.
Is_Switch : Is_Switch_Type (1 .. Arg_Count) := (others => False);
-- Indicates wich arguments on the command line are considered not be
-- switches or parameters to switches (leaving e.g. filenames,...)
Section : Section_Type (1 .. Arg_Count) := (others => 1);
-- Contains the number of the section associated with the current
-- switch. If this number is 0, then it is a section delimiter, which is
-- never returned by GetOpt.
Current_Argument : Natural := 1;
-- Number of the current argument parsed on the command line
Current_Index : Natural := 1;
-- Index in the current argument of the character to be processed
Current_Section : Section_Number := 1;
Expansion_It : aliased Expansion_Iterator;
-- When Get_Argument is expanding a file name, this is the iterator used
In_Expansion : Boolean := False;
-- True if we are expanding a file
Switch_Character : Character := '-';
-- The character at the beginning of the command line arguments,
-- indicating the beginning of a switch.
Stop_At_First : Boolean := False;
-- If it is True then Getopt stops at the first non-switch argument
end record;
Command_Line_Parser_Data : aliased Opt_Parser_Data
(Ada.Command_Line.Argument_Count);
-- The internal data used when parsing the command line
type Opt_Parser is access all Opt_Parser_Data;
Command_Line_Parser : constant Opt_Parser :=
Command_Line_Parser_Data'Access;
type Command_Line_Configuration_Record is record
Prefixes : GNAT.OS_Lib.Argument_List_Access;
-- The list of prefixes
Aliases : GNAT.OS_Lib.Argument_List_Access;
Expansions : GNAT.OS_Lib.Argument_List_Access;
-- The aliases. Both arrays have the same indices
end record;
type Command_Line_Configuration is access Command_Line_Configuration_Record;
type Command_Line is record
Config : Command_Line_Configuration;
Expanded : GNAT.OS_Lib.Argument_List_Access;
Params : GNAT.OS_Lib.Argument_List_Access;
-- Parameter for the corresponding switch in Expanded. The first
-- character is the separator (or ASCII.NUL if there is no separator)
Coalesce : GNAT.OS_Lib.Argument_List_Access;
Coalesce_Params : GNAT.OS_Lib.Argument_List_Access;
-- Cached version of the command line. This is recomputed every time the
-- command line changes. Switches are grouped as much as possible, and
-- aliases are used to reduce the length of the command line.
-- The parameters are not allocated, they point into Params, so must not
-- be freed.
end record;
type Command_Line_Iterator is record
List : GNAT.OS_Lib.Argument_List_Access;
Params : GNAT.OS_Lib.Argument_List_Access;
Current : Natural;
end record;
end GNAT.Command_Line;