1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxCmdLineParser
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 wxCmdLineEntryDesc::flags field is a combination of these bit masks.
12 Notice that by default (i.e. if flags are just 0), options are optional
13 (sic) and each call to wxCmdLineEntryDesc::AddParam() allows one more
14 parameter - this may be changed by giving non-default flags to it, i.e. use
15 wxCMD_LINE_OPTION_MANDATORY to require that the option is given and
16 wxCMD_LINE_PARAM_OPTIONAL to make a parameter optional. Also,
17 wxCMD_LINE_PARAM_MULTIPLE may be specified if the programs accepts a
18 variable number of parameters - but it only can be given for the last
19 parameter in the command line description. If you use this flag, you will
20 probably need to use wxCmdLineEntryDesc::GetParamCount() to retrieve the
21 number of parameters effectively specified after calling
22 wxCmdLineEntryDesc::Parse().
24 wxCMD_LINE_NEEDS_SEPARATOR can be specified to require a separator (either
25 a colon, an equal sign or white space) between the option name and its
26 value. By default, no separator is required.
30 wxCMD_LINE_OPTION_MANDATORY
= 0x01, ///< This option must be given.
31 wxCMD_LINE_PARAM_OPTIONAL
= 0x02, ///< The parameter may be omitted.
32 wxCMD_LINE_PARAM_MULTIPLE
= 0x04, ///< The parameter may be repeated.
33 wxCMD_LINE_OPTION_HELP
= 0x08, ///< This option is a help request.
34 wxCMD_LINE_NEEDS_SEPARATOR
= 0x10 ///< Must have a separator before the value.
38 The possible values of wxCmdLineEntryDesc::type which specifies the type of
39 the value accepted by an option.
41 enum wxCmdLineParamType
43 wxCMD_LINE_VAL_STRING
,
44 wxCMD_LINE_VAL_NUMBER
,
46 wxCMD_LINE_VAL_DOUBLE
,
51 The type of a command line entity used for wxCmdLineEntryDesc::kind.
53 enum wxCmdLineEntryType
58 wxCMD_LINE_NONE
///< Use this to terminate the list.
62 The structure wxCmdLineEntryDesc is used to describe the one command line
63 switch, option or parameter. An array of such structures should be passed
64 to wxCmdLineParser::SetDesc(). Also, the meanings of parameters of the
65 wxCmdLineParser::AddXXX() functions are the same as of the corresponding
66 fields in this structure.
68 The field @c shortName is the usual, short, name of the switch or the
69 option. @c longName is the corresponding long name or empty if the option
70 has no long name. Both of these fields are unused for the parameters. Both
71 the short and long option names can contain only letters, digits and the
74 @c description is used by the wxCmdLineEntryDesc::Usage() method to
75 construct a help message explaining the syntax of the program.
77 struct wxCmdLineEntryDesc
79 wxCmdLineEntryType kind
;
80 const char *shortName
;
82 const char *description
;
83 wxCmdLineParamType type
;
88 @class wxCmdLineParser
91 wxCmdLineParser is a class for parsing the command line.
93 It has the following features:
95 - distinguishes options, switches and parameters
96 - allows option grouping
97 - allows both short and long options
98 - automatically generates the usage message from the command line description
99 - checks types of the options values (number, date, ...).
101 To use it you should follow these steps:
103 -# @ref cmdlineparser_construction "Construct" an object of this class
104 giving it the command line to parse and optionally its description or
105 use the @c AddXXX() functions later.
107 -# Use Found() to retrieve the results.
109 In the documentation below the following terminology is used:
111 - @b switch: This is a boolean option which can be given or not, but which
112 doesn't have any value. We use the word switch to distinguish
113 such boolean options from more generic options like those
114 described below. For example, @c "-v" might be a switch
115 meaning "enable verbose mode".
116 - @b option: Option for us here is something which comes with a value 0
117 unlike a switch. For example, @c -o: @c filename might be an
118 option for specifying the name of the output file.
119 - @b parameter: This is a required program argument.
122 @section cmdlineparser_construction Construction
124 Before Parse() can be called, the command line parser object must have the
125 command line to parse and also the rules saying which switches, options and
126 parameters are valid - this is called command line description in what
129 You have complete freedom of choice as to when specify the required
130 information, the only restriction is that it must be done before calling
133 To specify the command line to parse you may use either one of constructors
134 accepting it (wxCmdLineParser(int, char**) or
135 wxCmdLineParser(const wxString&) usually) or, if you use the default
136 constructor, you can do it later by calling SetCmdLine().
138 The same holds for command line description: it can be specified either in
139 the constructor (with or without the command line itself) or constructed
140 later using either SetDesc() or combination of AddSwitch(), AddOption() and
143 Using constructors or SetDesc() uses a (usually const static) table
144 containing the command line description. If you want to decide which
145 options to accept during the run-time, using one of the AddXXX() functions
146 above might be preferable.
149 @section cmdlineparser_customization Customization
151 wxCmdLineParser has several global options which may be changed by the
152 application. All of the functions described in this section should be
153 called before Parse().
155 First global option is the support for long (also known as GNU-style)
156 options. The long options are the ones which start with two dashes and look
157 like "--verbose", i.e. they generally are complete words and not some
158 abbreviations of them. As long options are used by more and more
159 applications, they are enabled by default, but may be disabled with
160 DisableLongOptions().
162 Another global option is the set of characters which may be used to start
163 an option (otherwise, the word on the command line is assumed to be a
164 parameter). Under Unix, @c "-" is always used, but Windows has at least two
165 common choices for this: @c "-" and @c "/". Some programs also use "+". The
166 default is to use what suits most the current platform, but may be changed
167 with SetSwitchChars() method.
169 Finally, SetLogo() can be used to show some application-specific text
170 before the explanation given by Usage() function.
173 @section cmdlineparser_parsing Parsing the Command Line
175 After the command line description was constructed and the desired options
176 were set, you can finally call Parse() method. It returns 0 if the command
177 line was correct and was parsed, -1 if the help option was specified (this
178 is a separate case as, normally, the program will terminate after this) or
179 a positive number if there was an error during the command line parsing.
181 In the latter case, the appropriate error message and usage information are
182 logged by wxCmdLineParser itself using the standard wxWidgets logging
186 @section cmdlineparser_results Getting Results
188 After calling Parse() (and if it returned 0), you may access the results of
189 parsing using one of overloaded Found() methods.
191 For a simple switch, you will simply call Found to determine if the switch
192 was given or not, for an option or a parameter, you will call a version of
193 Found() which also returns the associated value in the provided variable.
194 All Found() functions return true if the switch or option were found in the
195 command line or false if they were not specified.
199 @category{appmanagement}
201 @see wxApp::argc, wxApp::argv, @ref page_samples_console "Console Sample"
203 class wxCmdLineParser
207 Default constructor, you must use SetCmdLine() later.
213 Constructor which specifies the command line to parse. This is the
214 traditional (Unix) command line format. The parameters @a argc and
215 @a argv have the same meaning as the typical @c main() function.
217 The second overloaded constructor is only available in Unicode build.
218 The first one is available in both ANSI and Unicode modes because under
219 some platforms the command line arguments are passed as ASCII strings
220 even to Unicode programs.
222 wxCmdLineParser(int argc
, char** argv
);
223 wxCmdLineParser(int argc
, wchar_t** argv
);
227 Constructor which specify the command line to parse in Windows format.
228 The parameter cmdline has the same meaning as the corresponding
229 parameter of @c WinMain().
231 wxCmdLineParser(const wxString
& cmdline
);
234 Specifies the @ref SetDesc() "command line description" but not the
235 command line. You must use SetCmdLine() later.
237 wxCmdLineParser(const wxCmdLineEntryDesc
* desc
);
240 Specifies both the command line (in Unix format) and the
241 @ref SetDesc() "command line description".
243 wxCmdLineParser(const wxCmdLineEntryDesc
* desc
, int argc
, char** argv
);
246 Specifies both the command line (in Windows format) and the
247 @ref SetDesc() "command line description".
249 wxCmdLineParser(const wxCmdLineEntryDesc
* desc
,
250 const wxString
& cmdline
);
253 Frees resources allocated by the object.
255 @note This destructor is not virtual, don't use this class
261 Add an option @a name with an optional long name @a lng (no long name
262 if it is empty, which is default) taking a value of the given type
263 (string by default) to the command line description.
265 void AddOption(const wxString
& name
,
266 const wxString
& lng
= wxEmptyString
,
267 const wxString
& desc
= wxEmptyString
,
268 wxCmdLineParamType type
= wxCMD_LINE_VAL_STRING
,
272 Add a parameter of the given @a type to the command line description.
274 void AddParam(const wxString
& desc
= wxEmptyString
,
275 wxCmdLineParamType type
= wxCMD_LINE_VAL_STRING
,
279 Add a switch @a name with an optional long name @a lng (no long name if
280 it is empty, which is default), description @a desc and flags @a flags
281 to the command line description.
283 void AddSwitch(const wxString
& name
,
284 const wxString
& lng
= wxEmptyString
,
285 const wxString
& desc
= wxEmptyString
,
289 Returns @true if long options are enabled, otherwise @false.
291 @see EnableLongOptions()
293 bool AreLongOptionsEnabled() const;
296 Breaks down the string containing the full command line in words. The
297 words are separated by whitespace. The quotes can be used in the input
298 string to quote the white space and the back slashes can be used to
301 static wxArrayString
ConvertStringToArgs(const wxChar cmdline
);
304 Identical to EnableLongOptions(@false).
306 void DisableLongOptions();
309 Enable or disable support for the long options.
311 As long options are not (yet) POSIX-compliant, this option allows to
314 @see @ref cmdlineparser_customization and AreLongOptionsEnabled()
316 void EnableLongOptions(bool enable
= true);
319 Returns @true if the given switch was found, @false otherwise.
321 bool Found(const wxString
& name
) const;
324 Returns true if an option taking a string value was found and stores
325 the value in the provided pointer (which should not be @NULL).
327 bool Found(const wxString
& name
, wxString
* value
) const;
330 Returns @true if an option taking an integer value was found and stores
331 the value in the provided pointer (which should not be @NULL).
333 bool Found(const wxString
& name
, long* value
) const;
336 Returns @true if an option taking a float value was found and stores
337 the value in the provided pointer (which should not be @NULL).
339 bool Found(const wxString
& name
, double* value
) const;
342 Returns @true if an option taking a date value was found and stores the
343 value in the provided pointer (which should not be @NULL).
345 bool Found(const wxString
& name
, wxDateTime
* value
) const;
348 Returns the value of Nth parameter (as string only).
350 wxString
GetParam(size_t n
= 0) const;
353 Returns the number of parameters found. This function makes sense
354 mostly if you had used @c wxCMD_LINE_PARAM_MULTIPLE flag.
356 size_t GetParamCount() const;
359 Parse the command line, return 0 if ok, -1 if @c "-h" or @c "--help"
360 option was encountered and the help message was given or a positive
361 value if a syntax error occurred.
364 If @true (default), the usage message is given if a syntax error
365 was encountered while parsing the command line or if help was
366 requested. If @false, only error messages about possible syntax
367 errors are given, use Usage to show the usage message from the
370 int Parse(bool giveUsage
= true);
374 Set the command line to parse after using one of the constructors which
377 void SetCmdLine(int argc
, char** argv
);
378 void SetCmdLine(int argc
, wchar_t** argv
);
379 void SetCmdLine(const wxString
& cmdline
);
383 Constructs the command line description.
385 Take the command line description from the wxCMD_LINE_NONE terminated
391 static const wxCmdLineEntryDesc cmdLineDesc[] =
393 { wxCMD_LINE_SWITCH, "v", "verbose", "be verbose" },
394 { wxCMD_LINE_SWITCH, "q", "quiet", "be quiet" },
396 { wxCMD_LINE_OPTION, "o", "output", "output file" },
397 { wxCMD_LINE_OPTION, "i", "input", "input dir" },
398 { wxCMD_LINE_OPTION, "s", "size", "output block size", wxCMD_LINE_VAL_NUMBER },
399 { wxCMD_LINE_OPTION, "d", "date", "output file date", wxCMD_LINE_VAL_DATE },
401 { wxCMD_LINE_PARAM, NULL, NULL, "input file", wxCMD_LINE_VAL_STRING, wxCMD_LINE_PARAM_MULTIPLE },
406 wxCmdLineParser parser;
408 parser.SetDesc(cmdLineDesc);
411 void SetDesc(const wxCmdLineEntryDesc
* desc
);
414 The @a logo is some extra text which will be shown by Usage() method.
416 void SetLogo(const wxString
& logo
);
419 @a switchChars contains all characters with which an option or switch
420 may start. Default is @c "-" for Unix, @c "-/" for Windows.
422 void SetSwitchChars(const wxString
& switchChars
);
425 Give the standard usage message describing all program options. It will
426 use the options and parameters descriptions specified earlier, so the
427 resulting message will not be helpful to the user unless the
428 descriptions were indeed specified.