| Version: 3.3.1

Public Member Functions | Static Public Member Functions | List of all members
wxCmdLineParser Class Reference
Class List by Category » Application and Process Management

`#include <wx/cmdline.h>`

## Detailed Description

wxCmdLineParser is a class for parsing the command line.

It has the following features:

- distinguishes options, switches and parameters
- allows option grouping
- allows both short and long options
- automatically generates the usage message from the command line description
- checks types of 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 the `AddXXX()` functions later.
2. Call Parse().
3. Use Found() to retrieve the results.

You can also use wxApp's default command line processing just overriding wxAppConsole::OnInitCmdLine() and wxAppConsole::OnCmdLineParsed().

In the documentation below the following terminology is used:

- switch: 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: a switch with a value associated to it. For example, `"-o filename"` might be an option for specifying the name of the output file.
- parameter: a required program argument.

# 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(int, char**) or wxCmdLineParser(const wxString&) 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 (with or without the command line itself) or constructed later using either SetDesc() or combination of AddSwitch(), AddOption(), AddParam() and AddUsageText() 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 "\--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 and SetUsageSynopsis() can be used to replace the default, automatically generated, brief program usage explanation string shown by it.

# Parsing the 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.

##

Library: wxBase
Category: Application and Process Management

See also
  wxApp::argc, wxApp::argv, Console Program Sample

## Public Member Functions
| wxCmdLineParser ()
| Default constructor, you must use SetCmdLine() later. More...
| wxCmdLineParser (int argc, char **argv)
| Constructor which specifies the command line to parse. More...
| wxCmdLineParser (int argc, wchar_t **argv)
| Constructor which specifies the command line to parse. More...
| wxCmdLineParser (const wxString &cmdline)
| Constructor which specify the command line to parse in Windows format. More...
| wxCmdLineParser (const wxCmdLineEntryDesc *desc)
| Specifies the command line description but not the command line. More...
| wxCmdLineParser (const wxCmdLineEntryDesc *desc, int argc, char **argv)
| Specifies both the command line (in Unix format) and the command line description. More...
| wxCmdLineParser (const wxCmdLineEntryDesc *desc, const wxString &cmdline)
| Specifies both the command line (in Windows format) and the command line description. More...
| ~wxCmdLineParser ()
| Frees resources allocated by the object. More...
void | AddLongOption (const wxString &lng, const wxString &desc=wxEmptyString, wxCmdLineParamType type=wxCMD_LINE_VAL_STRING, int flags=0)
| Adds an option with only long form. More...
void | AddLongSwitch (const wxString &lng, const wxString &desc=wxEmptyString, int flags=0)
| Adds a switch with only long form. More...
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. More...
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. More...
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. More...
void | AddUsageText (const wxString &text)
| Add a string text to the command line description shown by Usage(). More...
bool | AreLongOptionsEnabled () const
| Returns true if long options are enabled, otherwise false. More...
void | DisableLongOptions ()
| Identical to EnableLongOptions(false). More...
void | EnableLongOptions (bool enable=true)
| Enable or disable support for the long options. More...
bool | Found (const wxString &name) const
| Returns true if the given switch was found, false otherwise. More...
wxCmdLineSwitchState | FoundSwitch (const wxString &name) const
| Returns whether the switch was found on the command line and whether it was negated. More...
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 nullptr). More...
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 nullptr). More...
bool | Found (const wxString &name, double *value) const
| Returns true if an option taking a float value was found and stores the value in the provided pointer (which should not be nullptr). More...
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 nullptr). More...
wxString | GetParam (size_t n=0) const
| Returns the value of Nth parameter (as string only). More...
size_t | GetParamCount () const
| Returns the number of parameters found. More...
wxCmdLineArgs | GetArguments () const
| Returns the collection of arguments. More...
int | Parse (bool giveUsage=true, int wrapColumn=wxCMD_LINE_WRAP_AUTO)
| 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. More...
void | SetDesc (const wxCmdLineEntryDesc *desc)
| Constructs the command line description. More...
void | SetLogo (const wxString &logo)
| The logo is some extra text which will be shown by Usage() method. More...
void | SetUsageSynopsis (const wxString &synopsis)
| Set the usage synopsis string. More...
void | SetSwitchChars (const wxString &switchChars)
| switchChars contains all characters with which an option or switch may start. More...
void | Usage (int wrapColumn=wxCMD_LINE_WRAP_AUTO) const
| Give the standard usage message describing all program options. More...
wxString | GetUsageString (int wrapColumn=wxCMD_LINE_WRAP_AUTO) const
| Return the string containing the program usage description. More...
void | SetCmdLine (int argc, char **argv)
| Set the command line to parse after using one of the constructors which don't do it. More...
void | SetCmdLine (int argc, wchar_t **argv)
| Set the command line to parse after using one of the constructors which don't do it. More...
void | SetCmdLine (const wxString &cmdline)
| Set the command line to parse after using one of the constructors which don't do it. More...

## Static Public Member Functions
static wxArrayString | ConvertStringToArgs (const wxString &cmdline, wxCmdLineSplitType flags=wxCMD_LINE_SPLIT_DOS)
| Breaks down the string containing the full command line in words. More...

## Constructor & Destructor Documentation

## ◆ wxCmdLineParser() [1/7]

wxCmdLineParser::wxCmdLineParser | ( |  | ) |

Default constructor, you must use SetCmdLine() later.

## ◆ wxCmdLineParser() [2/7]

wxCmdLineParser::wxCmdLineParser | ( | int | argc,
|  | char ** | argv
| ) |  |

Constructor which specifies the command line to parse.

This is the traditional (Unix) command line format and the parameters argc and argv have the same meaning as the typical `main()` function.

## ◆ wxCmdLineParser() [3/7]

wxCmdLineParser::wxCmdLineParser | ( | int | argc,
|  | wchar_t ** | argv
| ) |  |

Constructor which specifies the command line to parse.

The parameters argc and argv have the same meaning as the typical `main()` function, but the latter uses wide character strings.

## ◆ wxCmdLineParser() [4/7]

wxCmdLineParser::wxCmdLineParser | ( | const wxString & | cmdline | ) |

Constructor which specify the command line to parse in Windows format.

The parameter cmdline has the same meaning as the corresponding parameter of `WinMain()`.

## ◆ wxCmdLineParser() [5/7]

wxCmdLineParser::wxCmdLineParser | ( | const wxCmdLineEntryDesc * | desc | ) |

Specifies the command line description but not the command line.

You must use SetCmdLine() later.

## ◆ wxCmdLineParser() [6/7]

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

Specifies both the command line (in Unix format) and the command line description.

## ◆ wxCmdLineParser() [7/7]

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

Specifies both the command line (in Windows format) and the command line description.

## ◆ ~wxCmdLineParser()

wxCmdLineParser::~wxCmdLineParser | ( |  | ) |

Frees resources allocated by the object.

Note
  This destructor is not virtual, don't use this class polymorphically.

## Member Function Documentation

## ◆ AddLongOption()

void wxCmdLineParser::AddLongOption | ( | const wxString & | lng,
|  | const wxString & | desc = `wxEmptyString`,
|  | wxCmdLineParamType | type = `wxCMD_LINE_VAL_STRING`,
|  | int | flags = `0`
| ) |  |

Adds an option with only long form.

This is just a convenient wrapper for AddOption() passing an empty string as short option name.

Since
  2.9.3

## ◆ AddLongSwitch()

void wxCmdLineParser::AddLongSwitch | ( | const wxString & | lng,
|  | const wxString & | desc = `wxEmptyString`,
|  | int | flags = `0`
| ) |  |

Adds a switch with only long form.

This is just a convenient wrapper for AddSwitch() passing an empty string as short switch name.

Since
  2.9.3

## ◆ AddOption()

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

## ◆ AddParam()

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

## ◆ AddSwitch()

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

## ◆ AddUsageText()

void wxCmdLineParser::AddUsageText | ( | const wxString & | text | ) |

Add a string text to the command line description shown by Usage().

Since
  2.9.0

## ◆ AreLongOptionsEnabled()

bool wxCmdLineParser::AreLongOptionsEnabled | ( |  | ) | const

Returns true if long options are enabled, otherwise false.

See also
  EnableLongOptions()

## ◆ ConvertStringToArgs()

static wxArrayString wxCmdLineParser::ConvertStringToArgs | ( | const wxString & | cmdline,
|  | wxCmdLineSplitType | flags = `wxCMD_LINE_SPLIT_DOS`
| ) |  |
| static

Breaks down the string containing the full command line in words.

Words are separated by whitespace and double quotes can be used to preserve the spaces inside the words.

By default, this function uses Windows-like word splitting algorithm, i.e. single quotes have no special meaning and backslash can't be used to escape spaces either. With `wxCMD_LINE_SPLIT_UNIX` flag Unix semantics is used, i.e. both single and double quotes can be used and backslash can be used to escape all the other special characters.

## ◆ DisableLongOptions()

void wxCmdLineParser::DisableLongOptions | ( |  | ) |

Identical to EnableLongOptions(false).

## ◆ EnableLongOptions()

void wxCmdLineParser::EnableLongOptions | ( | bool | enable = `true` | ) |

Enable or disable support for the long options.

As long options are not (yet) POSIX-compliant, this option allows disabling them.

See also
  Customization and AreLongOptionsEnabled()

## ◆ Found() [1/5]

bool wxCmdLineParser::Found | ( | const wxString & | name | ) | const

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

## ◆ Found() [2/5]

bool wxCmdLineParser::Found | ( | const wxString & | name,
|  | double * | value
| ) |  | const

Returns true if an option taking a float value was found and stores the value in the provided pointer (which should not be nullptr).

## ◆ Found() [3/5]

bool wxCmdLineParser::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 nullptr).

## ◆ Found() [4/5]

bool wxCmdLineParser::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 nullptr).

## ◆ Found() [5/5]

bool wxCmdLineParser::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 nullptr).

## ◆ FoundSwitch()

wxCmdLineSwitchState wxCmdLineParser::FoundSwitch | ( | const wxString & | name | ) | const

Returns whether the switch was found on the command line and whether it was negated.

This method can be used for any kind of switch but is especially useful for switches that can be negated, i.e. were added with wxCMD_LINE_SWITCH_NEGATABLE flag, as otherwise Found() is simpler to use.

However Found() doesn't allow to distinguish between switch specified normally, i.e. without dash following it, and negated switch, i.e. with the following dash. This method will return `wxCMD_SWITCH_ON` or `wxCMD_SWITCH_OFF` depending on whether the switch was negated or not. And if the switch was not found at all, `wxCMD_SWITCH_NOT_FOUND` is returned.

Since
  2.9.2

## ◆ GetArguments()

wxCmdLineArgs wxCmdLineParser::GetArguments | ( |  | ) | const

Returns the collection of arguments.

Note
  The returned object just refers to the command line parser. The command line parser must live longer than it.

See also
  wxCmdLineArgs

Since
  3.1.0

## ◆ GetParam()

wxString wxCmdLineParser::GetParam | ( | size_t | n = `0` | ) | const

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

## ◆ GetParamCount()

size_t wxCmdLineParser::GetParamCount | ( |  | ) | const

Returns the number of parameters found.

This function makes sense mostly if you had used `wxCMD_LINE_PARAM_MULTIPLE` flag.

## ◆ GetUsageString()

wxString wxCmdLineParser::GetUsageString | ( | int | wrapColumn = `wxCMD_LINE_WRAP_AUTO` | ) | const

Return the string containing the program usage description.

Call Usage() to directly show this string to the user.

Parameters

  wrapColumn | See Parse() for the description of this parameter. This parameter is new since wxWidgets 3.3.0.

## ◆ Parse()

int wxCmdLineParser::Parse | ( | bool | giveUsage = `true`,
|  | int | wrapColumn = `wxCMD_LINE_WRAP_AUTO`
| ) |  |

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 | If true (default), the usage message is given if a syntax error was encountered while parsing the command line or if help was requested. If false, only error messages about possible syntax errors are given, use Usage to show the usage message from the caller if needed.
  wrapColumn | When giveUsage is true, this parameter specifies the column at which the help text should be wrapped if given. When left as its default value of wxCMD_LINE_WRAP_AUTO, the text will be wrapped at the window boundary, if it was possible to detect it, or not at all otherwise. If the value of this parameter is wxCMD_LINE_WRAP_NONE, the text is never wrapped. Any other value specifies the column at which to wrap, e.g. 80. This parameter is new since wxWidgets 3.3.0.

## ◆ SetCmdLine() [1/3]

void wxCmdLineParser::SetCmdLine | ( | const wxString & | cmdline | ) |

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

## ◆ SetCmdLine() [2/3]

void wxCmdLineParser::SetCmdLine | ( | int | argc,
|  | char ** | argv
| ) |  |

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

## ◆ SetCmdLine() [3/3]

void wxCmdLineParser::SetCmdLine | ( | int | argc,
|  | wchar_t ** | argv
| ) |  |

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

## ◆ SetDesc()

void wxCmdLineParser::SetDesc | ( | const wxCmdLineEntryDesc * | desc | ) |

Constructs 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, nullptr, nullptr, "input file", wxCMD_LINE_VAL_STRING, wxCMD_LINE_PARAM_MULTIPLE },
{ wxCMD_LINE_NONE }
};
wxCmdLineParser parser;
parser.SetDesc(cmdLineDesc);
wxCmdLineParser
wxCmdLineParser is a class for parsing the command line.
Definition: cmdline.h:469
wxCmdLineParser::SetDesc
void SetDesc(const wxCmdLineEntryDesc *desc)
Constructs the command line description.
wxCMD_LINE_VAL_STRING
@ wxCMD_LINE_VAL_STRING
Definition: cmdline.h:56
wxCMD_LINE_VAL_DATE
@ wxCMD_LINE_VAL_DATE
Definition: cmdline.h:58
wxCMD_LINE_VAL_NUMBER
@ wxCMD_LINE_VAL_NUMBER
Definition: cmdline.h:57
wxCMD_LINE_SWITCH
@ wxCMD_LINE_SWITCH
A boolean argument of the program; e.g. -v to enable verbose mode.
Definition: cmdline.h:69
wxCMD_LINE_OPTION
@ wxCMD_LINE_OPTION
An argument with an associated value; e.g.
Definition: cmdline.h:73
wxCMD_LINE_PARAM
@ wxCMD_LINE_PARAM
A parameter: a required program argument.
Definition: cmdline.h:76
wxCMD_LINE_NONE
@ wxCMD_LINE_NONE
Use this to terminate the list.
Definition: cmdline.h:81
wxCMD_LINE_PARAM_MULTIPLE
@ wxCMD_LINE_PARAM_MULTIPLE
The parameter may be repeated.
Definition: cmdline.h:43
wxCmdLineEntryDesc
The structure wxCmdLineEntryDesc is used to describe a command line switch, option or parameter.
Definition: cmdline.h:143

## ◆ SetLogo()

void wxCmdLineParser::SetLogo | ( | const wxString & | logo | ) |

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

See also
  SetUsageSynopsis()

## ◆ SetSwitchChars()

void wxCmdLineParser::SetSwitchChars | ( | const wxString & | switchChars | ) |

switchChars contains all characters with which an option or switch may start.

Default is `"-"` for Unix, `"-/"` for Windows.

## ◆ SetUsageSynopsis()

void wxCmdLineParser::SetUsageSynopsis | ( | const wxString & | synopsis | ) |

Set the usage synopsis string.

This string will be shown before the options list in the usage message generated by Usage() instead of the automatically generated synopsis showing the application executable followed by all the options.

It can be useful to call this function with a simplified synopsis if the application has too many command line options for the auto-generated one to be really useful.

Since
  3.3.0

## ◆ Usage()

void wxCmdLineParser::Usage | ( | int | wrapColumn = `wxCMD_LINE_WRAP_AUTO` | ) | const

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.

Parameters

  wrapColumn | See Parse() for the description of this parameter. This parameter is new since wxWidgets 3.3.0.

See also
  SetLogo(), SetUsageSynopsis()