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_USAGE_TEXT
,
59 wxCMD_LINE_NONE
///< Use this to terminate the list.
63 The structure wxCmdLineEntryDesc is used to describe the one command line
64 switch, option or parameter. An array of such structures should be passed
65 to wxCmdLineParser::SetDesc(). Also, the meanings of parameters of the
66 wxCmdLineParser::AddXXX() functions are the same as of the corresponding
67 fields in this structure.
69 The field @c shortName is the usual, short, name of the switch or the
70 option. @c longName is the corresponding long name or empty if the option
71 has no long name. Both of these fields are unused for the parameters. Both
72 the short and long option names can contain only letters, digits and the
75 @c description is used by the wxCmdLineEntryDesc::Usage() method to
76 construct a help message explaining the syntax of the program.
78 struct wxCmdLineEntryDesc
80 wxCmdLineEntryType kind
;
81 const char *shortName
;
83 const char *description
;
84 wxCmdLineParamType type
;
89 @class wxCmdLineParser
92 wxCmdLineParser is a class for parsing the command line.
94 It has the following features:
96 - distinguishes options, switches and parameters
97 - allows option grouping
98 - allows both short and long options
99 - automatically generates the usage message from the command line description
100 - checks types of the options values (number, date, ...).
102 To use it you should follow these steps:
104 -# @ref cmdlineparser_construction "Construct" an object of this class
105 giving it the command line to parse and optionally its description or
106 use the @c AddXXX() functions later.
108 -# Use Found() to retrieve the results.
110 In the documentation below the following terminology is used:
112 - @b switch: This is a boolean option which can be given or not, but which
113 doesn't have any value. We use the word switch to distinguish
114 such boolean options from more generic options like those
115 described below. For example, @c "-v" might be a switch
116 meaning "enable verbose mode".
117 - @b option: Option for us here is something which comes with a value 0
118 unlike a switch. For example, @c -o: @c filename might be an
119 option for specifying the name of the output file.
120 - @b parameter: This is a required program argument.
121 - @b text: This is a text which can be shown in usage information.
124 @section cmdlineparser_construction Construction
126 Before Parse() can be called, the command line parser object must have the
127 command line to parse and also the rules saying which switches, options and
128 parameters are valid - this is called command line description in what
131 You have complete freedom of choice as to when specify the required
132 information, the only restriction is that it must be done before calling
135 To specify the command line to parse you may use either one of constructors
136 accepting it (wxCmdLineParser(int, char**) or
137 wxCmdLineParser(const wxString&) usually) or, if you use the default
138 constructor, you can do it later by calling SetCmdLine().
140 The same holds for command line description: it can be specified either in
141 the constructor (with or without the command line itself) or constructed
142 later using either SetDesc() or combination of AddSwitch(), AddOption(),
143 AddParam() and AddUsageText() methods.
145 Using constructors or SetDesc() uses a (usually const static) table
146 containing the command line description. If you want to decide which
147 options to accept during the run-time, using one of the AddXXX() functions
148 above might be preferable.
151 @section cmdlineparser_customization Customization
153 wxCmdLineParser has several global options which may be changed by the
154 application. All of the functions described in this section should be
155 called before Parse().
157 First global option is the support for long (also known as GNU-style)
158 options. The long options are the ones which start with two dashes and look
159 like "--verbose", i.e. they generally are complete words and not some
160 abbreviations of them. As long options are used by more and more
161 applications, they are enabled by default, but may be disabled with
162 DisableLongOptions().
164 Another global option is the set of characters which may be used to start
165 an option (otherwise, the word on the command line is assumed to be a
166 parameter). Under Unix, @c "-" is always used, but Windows has at least two
167 common choices for this: @c "-" and @c "/". Some programs also use "+". The
168 default is to use what suits most the current platform, but may be changed
169 with SetSwitchChars() method.
171 Finally, SetLogo() can be used to show some application-specific text
172 before the explanation given by Usage() function.
175 @section cmdlineparser_parsing Parsing the Command Line
177 After the command line description was constructed and the desired options
178 were set, you can finally call Parse() method. It returns 0 if the command
179 line was correct and was parsed, -1 if the help option was specified (this
180 is a separate case as, normally, the program will terminate after this) or
181 a positive number if there was an error during the command line parsing.
183 In the latter case, the appropriate error message and usage information are
184 logged by wxCmdLineParser itself using the standard wxWidgets logging
188 @section cmdlineparser_results Getting Results
190 After calling Parse() (and if it returned 0), you may access the results of
191 parsing using one of overloaded Found() methods.
193 For a simple switch, you will simply call Found to determine if the switch
194 was given or not, for an option or a parameter, you will call a version of
195 Found() which also returns the associated value in the provided variable.
196 All Found() functions return true if the switch or option were found in the
197 command line or false if they were not specified.
201 @category{appmanagement}
203 @see wxApp::argc, wxApp::argv, @ref page_samples_console "Console Sample"
205 class wxCmdLineParser
209 Default constructor, you must use SetCmdLine() later.
215 Constructor which specifies the command line to parse. This is the
216 traditional (Unix) command line format. The parameters @a argc and
217 @a argv have the same meaning as the typical @c main() function.
219 The second overloaded constructor is only available in Unicode build.
220 The first one is available in both ANSI and Unicode modes because under
221 some platforms the command line arguments are passed as ASCII strings
222 even to Unicode programs.
224 wxCmdLineParser(int argc
, char** argv
);
225 wxCmdLineParser(int argc
, wchar_t** argv
);
229 Constructor which specify the command line to parse in Windows format.
230 The parameter cmdline has the same meaning as the corresponding
231 parameter of @c WinMain().
233 wxCmdLineParser(const wxString
& cmdline
);
236 Specifies the @ref SetDesc() "command line description" but not the
237 command line. You must use SetCmdLine() later.
239 wxCmdLineParser(const wxCmdLineEntryDesc
* desc
);
242 Specifies both the command line (in Unix format) and the
243 @ref SetDesc() "command line description".
245 wxCmdLineParser(const wxCmdLineEntryDesc
* desc
, int argc
, char** argv
);
248 Specifies both the command line (in Windows format) and the
249 @ref SetDesc() "command line description".
251 wxCmdLineParser(const wxCmdLineEntryDesc
* desc
,
252 const wxString
& cmdline
);
255 Frees resources allocated by the object.
257 @note This destructor is not virtual, don't use this class
263 Add an option @a name with an optional long name @a lng (no long name
264 if it is empty, which is default) taking a value of the given type
265 (string by default) to the command line description.
267 void AddOption(const wxString
& name
,
268 const wxString
& lng
= wxEmptyString
,
269 const wxString
& desc
= wxEmptyString
,
270 wxCmdLineParamType type
= wxCMD_LINE_VAL_STRING
,
274 Add a parameter of the given @a type to the command line description.
276 void AddParam(const wxString
& desc
= wxEmptyString
,
277 wxCmdLineParamType type
= wxCMD_LINE_VAL_STRING
,
281 Add a switch @a name with an optional long name @a lng (no long name if
282 it is empty, which is default), description @a desc and flags @a flags
283 to the command line description.
285 void AddSwitch(const wxString
& name
,
286 const wxString
& lng
= wxEmptyString
,
287 const wxString
& desc
= wxEmptyString
,
291 Add a string @a text to the command line description shown by Usage().
295 void AddUsageText(const wxString
& text
);
298 Returns @true if long options are enabled, otherwise @false.
300 @see EnableLongOptions()
302 bool AreLongOptionsEnabled() const;
305 Breaks down the string containing the full command line in words. The
306 words are separated by whitespace. The quotes can be used in the input
307 string to quote the white space and the back slashes can be used to
310 static wxArrayString
ConvertStringToArgs(const wxChar cmdline
);
313 Identical to EnableLongOptions(@false).
315 void DisableLongOptions();
318 Enable or disable support for the long options.
320 As long options are not (yet) POSIX-compliant, this option allows to
323 @see @ref cmdlineparser_customization and AreLongOptionsEnabled()
325 void EnableLongOptions(bool enable
= true);
328 Returns @true if the given switch was found, @false otherwise.
330 bool Found(const wxString
& name
) const;
333 Returns true if an option taking a string value was found and stores
334 the value in the provided pointer (which should not be @NULL).
336 bool Found(const wxString
& name
, wxString
* value
) const;
339 Returns @true if an option taking an integer value was found and stores
340 the value in the provided pointer (which should not be @NULL).
342 bool Found(const wxString
& name
, long* value
) const;
345 Returns @true if an option taking a float value was found and stores
346 the value in the provided pointer (which should not be @NULL).
348 bool Found(const wxString
& name
, double* value
) const;
351 Returns @true if an option taking a date value was found and stores the
352 value in the provided pointer (which should not be @NULL).
354 bool Found(const wxString
& name
, wxDateTime
* value
) const;
357 Returns the value of Nth parameter (as string only).
359 wxString
GetParam(size_t n
= 0) const;
362 Returns the number of parameters found. This function makes sense
363 mostly if you had used @c wxCMD_LINE_PARAM_MULTIPLE flag.
365 size_t GetParamCount() const;
368 Parse the command line, return 0 if ok, -1 if @c "-h" or @c "--help"
369 option was encountered and the help message was given or a positive
370 value if a syntax error occurred.
373 If @true (default), the usage message is given if a syntax error
374 was encountered while parsing the command line or if help was
375 requested. If @false, only error messages about possible syntax
376 errors are given, use Usage to show the usage message from the
379 int Parse(bool giveUsage
= true);
383 Set the command line to parse after using one of the constructors which
386 void SetCmdLine(int argc
, char** argv
);
387 void SetCmdLine(int argc
, wchar_t** argv
);
388 void SetCmdLine(const wxString
& cmdline
);
392 Constructs the command line description.
394 Take the command line description from the wxCMD_LINE_NONE terminated
400 static const wxCmdLineEntryDesc cmdLineDesc[] =
402 { wxCMD_LINE_SWITCH, "v", "verbose", "be verbose" },
403 { wxCMD_LINE_SWITCH, "q", "quiet", "be quiet" },
405 { wxCMD_LINE_OPTION, "o", "output", "output file" },
406 { wxCMD_LINE_OPTION, "i", "input", "input dir" },
407 { wxCMD_LINE_OPTION, "s", "size", "output block size", wxCMD_LINE_VAL_NUMBER },
408 { wxCMD_LINE_OPTION, "d", "date", "output file date", wxCMD_LINE_VAL_DATE },
410 { wxCMD_LINE_PARAM, NULL, NULL, "input file", wxCMD_LINE_VAL_STRING, wxCMD_LINE_PARAM_MULTIPLE },
415 wxCmdLineParser parser;
417 parser.SetDesc(cmdLineDesc);
420 void SetDesc(const wxCmdLineEntryDesc
* desc
);
423 The @a logo is some extra text which will be shown by Usage() method.
425 void SetLogo(const wxString
& logo
);
428 @a switchChars contains all characters with which an option or switch
429 may start. Default is @c "-" for Unix, @c "-/" for Windows.
431 void SetSwitchChars(const wxString
& switchChars
);
434 Give the standard usage message describing all program options. It will
435 use the options and parameters descriptions specified earlier, so the
436 resulting message will not be helpful to the user unless the
437 descriptions were indeed specified.
444 Return the string containing the program usage description.
446 Call Usage() to directly show this string to the user.
448 wxString
GetUsageString() const;