wxCmdLineParser is a class for parsing the command line.
It has the following features:
To use it you should follow these steps:
In the documentation below the following terminology is used:
| switch | This is a boolean option which can be given or not, but which doesn't have any value. We use the word switch to distinguish such boolean options from more generic options like those described below. For example, -v might be a switch meaning "enable verbose mode". |
| option | Option for us here is something which comes with a value 0 unlike a switch. For example, -o:filename might be an option which allows to specify the name of the output file. |
| parameter | This is a required program argument. |
Derived from
No base class
Include files
<wx/cmdline.h>
Constants
The structure wxCmdLineEntryDesc is used to describe the one command line switch, option or parameter. An array of such structures should be passed to SetDesc(). Also, the meanings of parameters of the AddXXX() functions are the same as of the corresponding fields in this structure:
struct wxCmdLineEntryDesc
{
wxCmdLineEntryType kind;
const wxChar *shortName;
const wxChar *longName;
const wxChar *description;
wxCmdLineParamType type;
int flags;
};
The type of a command line entity is in the kind field and may be one of
the following constants:
enum wxCmdLineEntryType
{
wxCMD_LINE_SWITCH,
wxCMD_LINE_OPTION,
wxCMD_LINE_PARAM,
wxCMD_LINE_NONE // use this to terminate the list
}
The field shortName is the usual, short, name of the switch or the option. longName is the corresponding long name or NULL if the option has no long name. Both of these fields are unused for the parameters. Both the short and long option names can contain only letters, digits and the underscores.
description is used by the Usage() method to construct a help message explaining the syntax of the program.
The possible values of type which specifies the type of the value accepted by an option or parameter are:
enum wxCmdLineParamType
{
wxCMD_LINE_VAL_STRING, // default
wxCMD_LINE_VAL_NUMBER,
wxCMD_LINE_VAL_DATE,
wxCMD_LINE_VAL_NONE
}
Finally, the flags field is a combination of the following bit masks:
enum
{
wxCMD_LINE_OPTION_MANDATORY = 0x01, // this option must be given
wxCMD_LINE_PARAM_OPTIONAL = 0x02, // the parameter may be omitted
wxCMD_LINE_PARAM_MULTIPLE = 0x04, // the parameter may be repeated
wxCMD_LINE_OPTION_HELP = 0x08, // this option is a help request
wxCMD_LINE_NEEDS_SEPARATOR = 0x10, // must have sep before the value
}
Notice that by default (i.e. if flags are just 0), options are optional (sic) and each call to AddParam() allows one more parameter - this may be changed by giving non-default flags to it, i.e. use wxCMD_LINE_OPTION_MANDATORY to require that the option is given and wxCMD_LINE_PARAM_OPTIONAL to make a parameter optional. Also, wxCMD_LINE_PARAM_MULTIPLE may be specified if the programs accepts a variable number of parameters - but it only can be given for the last parameter in the command line description. If you use this flag, you will probably need to use GetParamCount to retrieve the number of parameters effectively specified after calling Parse.
The last flag wxCMD_LINE_NEEDS_SEPARATOR can be specified to require a separator (either a colon, an equal sign or white space) between the option name and its value. By default, no separator is required.
See also
wxApp::argc and wxApp::argv
console sample
Function groups
Construction
Customization
Parsing command line
Getting results
wxCmdLineParser::wxCmdLineParser
wxCmdLineParser::wxCmdLineParser
wxCmdLineParser::wxCmdLineParser
wxCmdLineParser::wxCmdLineParser
wxCmdLineParser::wxCmdLineParser
wxCmdLineParser::wxCmdLineParser
wxCmdLineParser::ConvertStringToArgs
wxCmdLineParser::SetCmdLine
wxCmdLineParser::SetCmdLine
wxCmdLineParser::~wxCmdLineParser
wxCmdLineParser::SetSwitchChars
wxCmdLineParser::EnableLongOptions
wxCmdLineParser::DisableLongOptions
wxCmdLineParser::AreLongOptionsEnabled
wxCmdLineParser::SetLogo
wxCmdLineParser::SetDesc
wxCmdLineParser::AddSwitch
wxCmdLineParser::AddOption
wxCmdLineParser::AddParam
wxCmdLineParser::Parse
wxCmdLineParser::Usage
wxCmdLineParser::Found
wxCmdLineParser::Found
wxCmdLineParser::Found
wxCmdLineParser::Found
wxCmdLineParser::GetParamCount
wxCmdLineParser::GetParam
Before Parse can be called, the command line parser object must have the command line to parse and also the rules saying which switches, options and parameters are valid - this is called command line description in what follows.
You have complete freedom of choice as to when specify the required information, the only restriction is that it must be done before calling Parse.
To specify the command line to parse you may use either one of constructors accepting it (wxCmdLineParser(argc, argv) or wxCmdLineParser usually) or, if you use the default constructor, you can do it later by calling SetCmdLine.
The same holds for command line description: it can be specified either in the constructor (without command line or together with it) or constructed later using either SetDesc or combination of AddSwitch, AddOption and AddParam methods.
Using constructors or SetDesc uses a (usually const static) table containing the command line description. If you want to decide which options to accept during the run-time, using one of the AddXXX() functions above might be preferable.
wxCmdLineParser has several global options which may be changed by the application. All of the functions described in this section should be called before Parse.
First global option is the support for long (also known as GNU-style) options. The long options are the ones which start with two dashes ("--") and look like this: --verbose, i.e. they generally are complete words and not some abbreviations of them. As long options are used by more and more applications, they are enabled by default, but may be disabled with DisableLongOptions.
Another global option is the set of characters which may be used to start an option (otherwise, the word on the command line is assumed to be a parameter). Under Unix, '-' is always used, but Windows has at least two common choices for this: '-' and '/'. Some programs also use '+'. The default is to use what suits most the current platform, but may be changed with SetSwitchChars method.
Finally, SetLogo can be used to show some application-specific text before the explanation given by Usage function.
After the command line description was constructed and the desired options were set, you can finally call Parse method. It returns 0 if the command line was correct and was parsed, -1 if the help option was specified (this is a separate case as, normally, the program will terminate after this) or a positive number if there was an error during the command line parsing.
In the latter case, the appropriate error message and usage information are logged by wxCmdLineParser itself using the standard wxWidgets logging functions.
After calling Parse (and if it returned 0), you may access the results of parsing using one of overloaded Found() methods.
For a simple switch, you will simply call Found to determine if the switch was given or not, for an option or a parameter, you will call a version of Found() which also returns the associated value in the provided variable. All Found() functions return true if the switch or option were found in the command line or false if they were not specified.
wxCmdLineParser()
Default constructor. You must use SetCmdLine later.
wxCmdLineParser(int argc, char** argv)
wxCmdLineParser(int argc, wchar_t** argv)
Constructor specifies the command line to parse. This is the traditional (Unix) command line format. The parameters argc and argv have the same meaning as for main() function.
The second overloaded constructor is only available in Unicode build. The first one is available in both ANSI and Unicode modes because under some platforms the command line arguments are passed as ASCII strings even to Unicode programs.
wxCmdLineParser(const wxString& cmdline)
Constructor specifies the command line to parse in Windows format. The parameter cmdline has the same meaning as the corresponding parameter of WinMain().
wxCmdLineParser(const wxCmdLineEntryDesc* desc)
Same as wxCmdLineParser, but also specifies the command line description.
wxCmdLineParser(const wxCmdLineEntryDesc* desc, int argc, char** argv)
Same as wxCmdLineParser, but also specifies the command line description.
wxCmdLineParser(const wxCmdLineEntryDesc* desc, const wxString& cmdline)
Same as wxCmdLineParser, but also specifies the command line description.
static wxArrayString ConvertStringToArgs(const wxChar *cmdline)
Breaks down the string containing the full command line in words. The words are separated by whitespace. The quotes can be used in the input string to quote the white space and the back slashes can be used to quote the quotes.
void SetCmdLine(int argc, char** argv)
void SetCmdLine(int argc, wchar_t** argv)
Set command line to parse after using one of the constructors which don't do it. The second overload of this function is only available in Unicode build.
See also
void SetCmdLine(const wxString& cmdline)
Set command line to parse after using one of the constructors which don't do it.
See also
~wxCmdLineParser()
Frees resources allocated by the object.
NB: destructor is not virtual, don't use this class polymorphically.
void SetSwitchChars(const wxString& switchChars)
switchChars contains all characters with which an option or switch may start. Default is "-" for Unix, "-/" for Windows.
void EnableLongOptions(bool enable = true)
Enable or disable support for the long options.
As long options are not (yet) POSIX-compliant, this option allows to disable them.
See also
Customization and AreLongOptionsEnabled
void DisableLongOptions()
Identical to EnableLongOptions(false).
bool AreLongOptionsEnabled()
Returns true if long options are enabled, otherwise false.
See also
void SetLogo(const wxString& logo)
logo is some extra text which will be shown by Usage method.
void SetDesc(const wxCmdLineEntryDesc* desc)
Construct the command line description
Take the command line description from the wxCMD_LINE_NONE terminated table.
Example of usage:
static const wxCmdLineEntryDesc cmdLineDesc[] =
{
{ wxCMD_LINE_SWITCH, "v", "verbose", "be verbose" },
{ wxCMD_LINE_SWITCH, "q", "quiet", "be quiet" },
{ wxCMD_LINE_OPTION, "o", "output", "output file" },
{ wxCMD_LINE_OPTION, "i", "input", "input dir" },
{ wxCMD_LINE_OPTION, "s", "size", "output block size", wxCMD_LINE_VAL_NUMBER },
{ wxCMD_LINE_OPTION, "d", "date", "output file date", wxCMD_LINE_VAL_DATE },
{ wxCMD_LINE_PARAM, NULL, NULL, "input file", wxCMD_LINE_VAL_STRING, wxCMD_LINE_PARAM_MULTIPLE },
{ wxCMD_LINE_NONE }
};
wxCmdLineParser parser;
parser.SetDesc(cmdLineDesc);
void AddSwitch(const wxString& name, const wxString& lng = wxEmptyString, const wxString& desc = wxEmptyString, int flags = 0)
Add a switch name with an optional long name lng (no long name if it is empty, which is default), description desc and flags flags to the command line description.
void AddOption(const wxString& name, const wxString& lng = wxEmptyString, const wxString& desc = wxEmptyString, wxCmdLineParamType type = wxCMD_LINE_VAL_STRING, int flags = 0)
Add an option name with an optional long name lng (no long name if it is empty, which is default) taking a value of the given type (string by default) to the command line description.
void AddParam(const wxString& desc = wxEmptyString, wxCmdLineParamType type = wxCMD_LINE_VAL_STRING, int flags = 0)
Add a parameter of the given type to the command line description.
int Parse(bool giveUsage = true)
Parse the command line, return 0 if ok, -1 if "-h" or "--help" option was encountered and the help message was given or a positive value if a syntax error occurred.
Parameters
giveUsage
void Usage()
Give the standard usage message describing all program options. It will use the options and parameters descriptions specified earlier, so the resulting message will not be helpful to the user unless the descriptions were indeed specified.
See also
bool Found(const wxString& name) const
Returns true if the given switch was found, false otherwise.
bool Found(const wxString& name, wxString* value) const
Returns true if an option taking a string value was found and stores the value in the provided pointer (which should not be NULL).
bool Found(const wxString& name, long* value) const
Returns true if an option taking an integer value was found and stores the value in the provided pointer (which should not be NULL).
bool Found(const wxString& name, wxDateTime* value) const
Returns true if an option taking a date value was found and stores the value in the provided pointer (which should not be NULL).
size_t GetParamCount() const
Returns the number of parameters found. This function makes sense mostly if you had used wxCMD_LINE_PARAM_MULTIPLE flag.
wxString GetParam(size_t n = 0u) const
Returns the value of Nth parameter (as string only for now).
See also