Contents Up Previous Next

wxCmdLineParser

wxCmdLineParser is a class for parsing the command line.

It has the following features:

  1. distinguishes options, switches and parameters; allows option grouping
  2. allows both short and long options
  3. automatically generates the usage message from the command line description
  4. does type checks on the options values (number, date, ...).

To use it you should follow these steps:

  1. construct an object of this class giving it the command line to parse and optionally its description or use AddXXX() functions later
  2. call Parse()
  3. use Found() to retrieve the results

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


Construction

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.


Customization

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.


Parsing command line

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.


Getting results

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::wxCmdLineParser

wxCmdLineParser()

Default constructor. You must use SetCmdLine later.


wxCmdLineParser::wxCmdLineParser

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::wxCmdLineParser

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::wxCmdLineParser

wxCmdLineParser(const wxCmdLineEntryDesc* desc)

Same as wxCmdLineParser, but also specifies the command line description.


wxCmdLineParser::wxCmdLineParser

wxCmdLineParser(const wxCmdLineEntryDesc* desc, int argc, char** argv)

Same as wxCmdLineParser, but also specifies the command line description.


wxCmdLineParser::wxCmdLineParser

wxCmdLineParser(const wxCmdLineEntryDesc* desc, const wxString& cmdline)

Same as wxCmdLineParser, but also specifies the command line description.


wxCmdLineParser::ConvertStringToArgs

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.


wxCmdLineParser::SetCmdLine

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

wxCmdLineParser


wxCmdLineParser::SetCmdLine

void SetCmdLine(const wxString& cmdline)

Set command line to parse after using one of the constructors which don't do it.

See also

wxCmdLineParser


wxCmdLineParser::~wxCmdLineParser

~wxCmdLineParser()

Frees resources allocated by the object.

NB: destructor is not virtual, don't use this class polymorphically.


wxCmdLineParser::SetSwitchChars

void SetSwitchChars(const wxString& switchChars)

switchChars contains all characters with which an option or switch may start. Default is "-" for Unix, "-/" for Windows.


wxCmdLineParser::EnableLongOptions

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


wxCmdLineParser::DisableLongOptions

void DisableLongOptions()

Identical to EnableLongOptions(false).


wxCmdLineParser::AreLongOptionsEnabled

bool AreLongOptionsEnabled()

Returns true if long options are enabled, otherwise false.

See also

EnableLongOptions


wxCmdLineParser::SetLogo

void SetLogo(const wxString& logo)

logo is some extra text which will be shown by Usage method.


wxCmdLineParser::SetDesc

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);

wxCmdLineParser::AddSwitch

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.


wxCmdLineParser::AddOption

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.


wxCmdLineParser::AddParam

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.


wxCmdLineParser::Parse

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


wxCmdLineParser::Usage

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

SetLogo


wxCmdLineParser::Found

bool Found(const wxString& name) const

Returns true if the given switch was found, false otherwise.


wxCmdLineParser::Found

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).


wxCmdLineParser::Found

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).


wxCmdLineParser::Found

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).


wxCmdLineParser::GetParamCount

size_t GetParamCount() const

Returns the number of parameters found. This function makes sense mostly if you had used wxCMD_LINE_PARAM_MULTIPLE flag.


wxCmdLineParser::GetParam

wxString GetParam(size_t n = 0u) const

Returns the value of Nth parameter (as string only for now).

See also

GetParamCount