blob: e5f493e1128ee7d3bca2c7ae5b1fe4dfc988beb1 [file] [log] [blame]
-- --
-- --
-- G N A T . C O M M A N D _ L I N E --
-- --
-- S p e c --
-- --
-- Copyright (C) 1999-2021, 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 --
-- --
-- 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 --
-- <>. --
-- --
-- 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 be called either after Getopt has returned ASCII.NUL or
-- after Getopt procedure call.
-- If Do_Expansion is True, then the parameter on the command line will
-- be considered as a filename with wildcards, 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 wildcard references.
-- When there are no more arguments on the command line, this function
-- returns an empty string.
function Get_Argument
(Do_Expansion : Boolean := False;
Parser : Opt_Parser := Command_Line_Parser;
End_Of_Arguments : out Boolean) return String;
-- The same as above but able to distinguish empty element in argument list
-- from end of arguments.
-- End_Of_Arguments is True if the end of the command line has been reached
-- (i.e. all available arguments have been returned by previous calls to
-- Get_Argument).
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 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 wildcard 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 := "";
Argument : String := "ARG");
-- 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).
-- Argument is the name of the argument, as displayed in the automatic
-- help message. It is always capitalized for consistency.
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 an erroneous
-- memory access may occur.
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;
Argument : String := "ARG");
-- 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. The switch must accept an argument.
procedure Define_Switch
(Config : in out Command_Line_Configuration;
Output : access GNAT.Strings.String_Access;
Switch : String := "";
Long_Switch : String := "";
Help : String := "";
Section : String := "";
Argument : String := "ARG");
-- 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 if it does not have a value already (otherwise it is left as is
-- so that you can specify the default value directly in the declaration
-- of the variable). The switch must accept an argument.
type Value_Callback is access procedure (Switch, Value : String);
procedure Define_Switch
(Config : in out Command_Line_Configuration;
Callback : not null Value_Callback;
Switch : String := "";
Long_Switch : String := "";
Help : String := "";
Section : String := "";
Argument : String := "ARG");
-- Call Callback for each instance of Switch. The callback is given the
-- actual switch and the corresponding value. The switch must accept
-- an argument.
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 (i.e. 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;
-- Raised when the program should exit because Getopt below has seen
-- a -h or --help switch.
procedure Getopt
(Config : Command_Line_Configuration;
Callback : Switch_Handler := null;
Parser : Opt_Parser := Command_Line_Parser;
Concatenate : Boolean := True;
Quiet : Boolean := False);
-- 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.
-- If the Quiet parameter is True then the error message is not displayed.
-- 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 (i.e. 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;
Switch : String;
Parameter : String := "";
Separator : Character := ASCII.NUL;
Section : String := "";
Add_Before : Boolean := False);
-- 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 what the parameter applies to.
-- If the switch is part of a section, then it should be specified so that
-- the switch is correctly placed in the command line, and the section
-- added if not already present. For example, to add the -g switch into the
-- -cargs section, you need to call (Cmd, "-g", Section => "-cargs").
-- [Separator], if specified, overrides the separator that was defined
-- through Define_Switch. For instance, if the switch was defined as
-- "-from:", the separator defaults to a space. But if your application
-- uses unusual separators not supported by GNAT.Command_Line (for instance
-- it requires ":"), you can specify this separator here.
-- For instance,
-- Add_Switch(Cmd, "-from", "bar", ':')
-- results in
-- -from:bar
-- rather than the default
-- -from bar
-- Note however that Getopt doesn't know how to handle ":" as a separator.
-- So the recommendation is to declare the switch as "-from!" (i.e. no
-- space between the switch and its parameter). Then Getopt will return
-- ":bar" as the parameter, and you can trim the ":" in your application.
-- Invalid_Section is raised if Section was not defined in the
-- configuration of the command line.
-- Add_Before allows insertion of the switch at the beginning of the
-- command line.
procedure Add_Switch
(Cmd : in out Command_Line;
Switch : String;
Parameter : String := "";
Separator : Character := ASCII.NUL;
Section : String := "";
Add_Before : Boolean := False;
Success : out Boolean);
-- Same as above, returning the status of the operation
procedure Remove_Switch
(Cmd : in out Command_Line;
Switch : String;
Remove_All : Boolean := False;
Has_Parameter : Boolean := False;
Section : String := "");
-- 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.
-- If Has_Parameter is set to True, then only switches having a parameter
-- are removed.
-- If the switch belongs to a section, then this section should be
-- specified: Remove_Switch (Cmd_Line, "-g", Section => "-cargs") called
-- on the command line "-g -cargs -g" will result in "-g", while if
-- called with (Cmd_Line, "-g") this will result in "-cargs -g".
-- If Remove_All is set, then both "-g" will be removed.
procedure Remove_Switch
(Cmd : in out Command_Line;
Switch : String;
Remove_All : Boolean := False;
Has_Parameter : Boolean := False;
Section : String := "";
Success : out Boolean);
-- Same as above, reporting the success of the operation (Success is False
-- if no switch was removed).
procedure Remove_Switch
(Cmd : in out Command_Line;
Switch : String;
Parameter : String;
Section : String := "");
-- Remove a switch with a specific parameter. If Parameter is the empty
-- string, then only a switch with no parameter will be removed.
procedure Free (Cmd : in out Command_Line);
-- Free the memory used by Cmd
-- Iteration --
-- When a command line was created with the above, you can then iterate
-- over its contents using the following iterator.
type Command_Line_Iterator is private;
procedure Start
(Cmd : in out Command_Line;
Iter : in out Command_Line_Iterator;
Expanded : Boolean := False);
-- 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 Is_New_Section (Iter : Command_Line_Iterator) return Boolean;
function Current_Section (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 Build
(Line : in out Command_Line;
Args : out GNAT.OS_Lib.Argument_List_Access;
Expanded : Boolean := False;
Switch_Char : Character := '-');
-- This is a wrapper using the Command_Line_Iterator. It provides a simple
-- way to get all switches (grouped as much as possible), and possibly
-- create an Opt_Parser.
-- Args must be freed by the caller.
-- Expanded has the same meaning as in Start.
procedure Try_Help;
-- Output a message on standard error to indicate how to get the usage for
-- the executable. This procedure should only be called when the executable
-- accepts switch --help. When this procedure is called by executable xxx,
-- the following message is displayed on standard error:
-- try "xxx --help" for more information.
Max_Depth : constant := 100;
-- Maximum depth of subdirectories
Max_Path_Length : constant := 1024;
-- Maximum length of relative path
type Depth is range 1 .. Max_Depth;
type Level is record
Name_Last : Natural := 0;
Dir : GNAT.Directory_Operations.Dir_Type;
end record;
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 : Natural;
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
-- the pattern.
Dir_Name : String (1 .. Max_Path_Length);
Current_Depth : Depth := 1;
Levels : Level_Array;
Regexp : GNAT.Regexp.Regexp;
-- Regular expression built with the pattern
Maximum_Depth : Depth := 1;
-- The maximum depth of directories, reflecting the number of directory
-- 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
-- The internal data used when parsing the command line
type Opt_Parser is access all Opt_Parser_Data;
Command_Line_Parser : constant Opt_Parser :=
type Switch_Type is (Switch_Untyped,
type Switch_Definition (Typ : Switch_Type := Switch_Untyped) is record
Switch : GNAT.OS_Lib.String_Access;
Long_Switch : GNAT.OS_Lib.String_Access;
Section : GNAT.OS_Lib.String_Access;
Help : GNAT.OS_Lib.String_Access;
Argument : GNAT.OS_Lib.String_Access;
-- null if "ARG".
-- Name of the argument for this switch.
case Typ is
when Switch_Untyped =>
when Switch_Boolean =>
Boolean_Output : access Boolean;
Boolean_Value : Boolean; -- will set Output to that value
when Switch_Integer =>
Integer_Output : access Integer;
Integer_Initial : Integer;
Integer_Default : Integer;
when Switch_String =>
String_Output : access GNAT.Strings.String_Access;
when Switch_Callback =>
Callback : Value_Callback;
end case;
end record;
type Switch_Definitions is array (Natural range <>) of Switch_Definition;
type Switch_Definitions_List is access all Switch_Definitions;
-- [Switch] includes the leading '-'
type Alias_Definition is record
Alias : GNAT.OS_Lib.String_Access;
Expansion : GNAT.OS_Lib.String_Access;
Section : GNAT.OS_Lib.String_Access;
end record;
type Alias_Definitions is array (Natural range <>) of Alias_Definition;
type Alias_Definitions_List is access all Alias_Definitions;
type Command_Line_Configuration_Record is record
Prefixes : GNAT.OS_Lib.Argument_List_Access;
-- The list of prefixes
Sections : GNAT.OS_Lib.Argument_List_Access;
-- The list of sections
Star_Switch : Boolean := False;
-- Whether switches not described in this configuration should be
-- returned to the user (True). If False, an exception Invalid_Switch
-- is raised.
Aliases : Alias_Definitions_List;
Usage : GNAT.OS_Lib.String_Access;
Help : GNAT.OS_Lib.String_Access;
Help_Msg : GNAT.OS_Lib.String_Access;
Switches : Switch_Definitions_List;
-- List of expected switches (Used when expanding switch groups)
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).
Sections : GNAT.OS_Lib.Argument_List_Access;
-- The list of sections
Coalesce : GNAT.OS_Lib.Argument_List_Access;
Coalesce_Params : GNAT.OS_Lib.Argument_List_Access;
Coalesce_Sections : 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 they must
-- not be freed.
end record;
type Command_Line_Iterator is record
List : GNAT.OS_Lib.Argument_List_Access;
Sections : GNAT.OS_Lib.Argument_List_Access;
Params : GNAT.OS_Lib.Argument_List_Access;
Current : Natural;
end record;
end GNAT.Command_Line;