]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/cmdline.h
Deprecate wxWindow::MakeModal().
[wxWidgets.git] / interface / wx / cmdline.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: cmdline.h
e54c96f1 3// Purpose: interface of wxCmdLineParser
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
526954c5 6// Licence: wxWindows licence
23324ae1
FM
7/////////////////////////////////////////////////////////////////////////////
8
d18d9f60
BP
9/**
10 wxCmdLineEntryDesc::flags field is a combination of these bit masks.
11
12 Notice that by default (i.e. if flags are just 0), options are optional
7bdb010f 13 (sic) and each call to wxCmdLineParser::AddParam() allows one more
d18d9f60 14 parameter - this may be changed by giving non-default flags to it, i.e. use
7bdb010f
FM
15 @c wxCMD_LINE_OPTION_MANDATORY to require that the option is given and
16 @c wxCMD_LINE_PARAM_OPTIONAL to make a parameter optional.
17
18 Also, @c wxCMD_LINE_PARAM_MULTIPLE may be specified if the programs accepts a
d18d9f60
BP
19 variable number of parameters - but it only can be given for the last
20 parameter in the command line description. If you use this flag, you will
21 probably need to use wxCmdLineEntryDesc::GetParamCount() to retrieve the
22 number of parameters effectively specified after calling
23 wxCmdLineEntryDesc::Parse().
24
7bdb010f 25 @c wxCMD_LINE_NEEDS_SEPARATOR can be specified to require a separator (either
d18d9f60
BP
26 a colon, an equal sign or white space) between the option name and its
27 value. By default, no separator is required.
a6bf0c95
VZ
28
29 @c wxCMD_LINE_SWITCH_NEGATABLE can be specified if you want to allow the
30 user to specify the switch in both normal form and in negated one (e.g.
31 /R-). You will need to use wxCmdLineParser::FoundSwitch() to distinguish
32 between the normal and negated forms of the switch. This flag is new since
33 wxWidgets 2.9.2.
d18d9f60 34*/
7bdb010f 35enum wxCmdLineEntryFlags
d18d9f60
BP
36{
37 wxCMD_LINE_OPTION_MANDATORY = 0x01, ///< This option must be given.
38 wxCMD_LINE_PARAM_OPTIONAL = 0x02, ///< The parameter may be omitted.
39 wxCMD_LINE_PARAM_MULTIPLE = 0x04, ///< The parameter may be repeated.
40 wxCMD_LINE_OPTION_HELP = 0x08, ///< This option is a help request.
a6bf0c95
VZ
41 wxCMD_LINE_NEEDS_SEPARATOR = 0x10, ///< Must have a separator before the value.
42 wxCMD_LINE_SWITCH_NEGATABLE = 0x20 ///< This switch can be negated (e.g. /S-)
d18d9f60
BP
43};
44
45/**
7bdb010f 46 The possible values of wxCmdLineEntryDesc::type which specify the type of
d18d9f60
BP
47 the value accepted by an option.
48*/
49enum wxCmdLineParamType
50{
51 wxCMD_LINE_VAL_STRING,
52 wxCMD_LINE_VAL_NUMBER,
53 wxCMD_LINE_VAL_DATE,
54 wxCMD_LINE_VAL_DOUBLE,
55 wxCMD_LINE_VAL_NONE
56};
57
58/**
59 The type of a command line entity used for wxCmdLineEntryDesc::kind.
60*/
61enum wxCmdLineEntryType
62{
7bdb010f 63 /// A boolean argument of the program; e.g. @c -v to enable verbose mode.
d18d9f60 64 wxCMD_LINE_SWITCH,
7bdb010f
FM
65
66 /// An argument with an associated value; e.g. @c "-o filename" to specify
67 /// an optional output filename.
d18d9f60 68 wxCMD_LINE_OPTION,
7bdb010f
FM
69
70 /// A parameter: a required program argument.
d18d9f60 71 wxCMD_LINE_PARAM,
7bdb010f
FM
72
73 /// Additional usage text. See wxCmdLineParser::AddUsageText.
e559d790 74 wxCMD_LINE_USAGE_TEXT,
7bdb010f 75
d18d9f60
BP
76 wxCMD_LINE_NONE ///< Use this to terminate the list.
77};
78
a6bf0c95
VZ
79/**
80 The state of a switch as returned by wxCmdLineParser::FoundSwitch().
81
82 @since 2.9.2
83*/
84enum wxCmdLineSwitchState
85{
86 /// The switch was found in negated form, i.e. followed by a '-'.
87 wxCMD_SWITCH_OFF,
88
89 /// The switch was not found at all on the command line.
90 wxCMD_SWITCH_NOT_FOUND
91
92 /// The switch was found (and was not negated)
93 wxCMD_SWITCH_ON
94};
95
96
a4761b4c 97/**
c0e97a5e 98 Flags determining wxCmdLineParser::ConvertStringToArgs() behaviour.
a4761b4c
VZ
99 */
100enum wxCmdLineSplitType
101{
102 wxCMD_LINE_SPLIT_DOS,
103 wxCMD_LINE_SPLIT_UNIX
104};
105
d18d9f60 106/**
7bdb010f 107 The structure wxCmdLineEntryDesc is used to describe a command line
d18d9f60 108 switch, option or parameter. An array of such structures should be passed
3d46a376
FM
109 to wxCmdLineParser::SetDesc().
110
7bdb010f 111 Note that the meanings of parameters of the wxCmdLineParser::AddXXX() functions
3d46a376 112 are the same as of the corresponding fields in this structure.
d18d9f60
BP
113*/
114struct wxCmdLineEntryDesc
115{
7bdb010f
FM
116 /**
117 The kind of this program argument.
118 See ::wxCmdLineEntryType for more info.
119 */
d18d9f60 120 wxCmdLineEntryType kind;
3d46a376
FM
121
122 /**
7bdb010f
FM
123 The usual, short, name of the switch or the option.
124
125 It may contain only letters, digits and the underscores.
126 This field is unused if <tt>kind == wxCMD_LINE_PARAM</tt>.
3d46a376 127 */
d18d9f60 128 const char *shortName;
3d46a376
FM
129
130 /**
7bdb010f
FM
131 The long name for this program argument (may be empty if the option
132 has no long name).
133
134 It may contain only letters, digits and the underscores.
135 This field is unused if <tt>kind == wxCMD_LINE_PARAM</tt>.
3d46a376 136 */
d18d9f60 137 const char *longName;
3d46a376
FM
138
139 /**
7bdb010f 140 This description is used by the wxCmdLineParser::Usage() method to
3d46a376
FM
141 construct a help message explaining the syntax of the program.
142 */
d18d9f60 143 const char *description;
3d46a376 144
7bdb010f
FM
145 /**
146 The type associated with this option (ignored if <tt>kind != wxCMD_LINE_OPTION</tt>).
147 See ::wxCmdLineParamType for more info.
148 */
d18d9f60 149 wxCmdLineParamType type;
7bdb010f
FM
150
151 /**
152 A combination of one or more ::wxCmdLineEntryFlags enum values.
153 */
d18d9f60
BP
154 int flags;
155};
156
23324ae1
FM
157/**
158 @class wxCmdLineParser
7c913512 159
23324ae1 160 wxCmdLineParser is a class for parsing the command line.
7c913512 161
23324ae1 162 It has the following features:
7c913512 163
779288b4
VZ
164 - distinguishes options, switches and parameters
165 - allows option grouping
166 - allows both short and long options
167 - automatically generates the usage message from the command line description
168 - checks types of the options values (number, date, ...).
7c913512 169
23324ae1 170 To use it you should follow these steps:
7c913512 171
d18d9f60
BP
172 -# @ref cmdlineparser_construction "Construct" an object of this class
173 giving it the command line to parse and optionally its description or
174 use the @c AddXXX() functions later.
175 -# Call Parse().
176 -# Use Found() to retrieve the results.
7c913512 177
3d46a376
FM
178 You can also use wxApp's default command line processing just overriding
179 wxAppConsole::OnInitCmdLine() and wxAppConsole::OnCmdLineParsed().
180
23324ae1 181 In the documentation below the following terminology is used:
7c913512 182
7bdb010f
FM
183 - @b switch: a boolean option which can be given or not, but which doesn't have
184 any value. We use the word @e switch to distinguish
d18d9f60
BP
185 such boolean options from more generic options like those
186 described below. For example, @c "-v" might be a switch
187 meaning "enable verbose mode".
7bdb010f
FM
188 - @b option: a switch with a value associated to it.
189 For example, @c "-o filename" might be an
a15c16bf 190 option for specifying the name of the output file.
7bdb010f 191 - @b parameter: a required program argument.
d18d9f60
BP
192
193
194 @section cmdlineparser_construction Construction
195
196 Before Parse() can be called, the command line parser object must have the
197 command line to parse and also the rules saying which switches, options and
198 parameters are valid - this is called command line description in what
199 follows.
200
201 You have complete freedom of choice as to when specify the required
202 information, the only restriction is that it must be done before calling
203 Parse().
204
205 To specify the command line to parse you may use either one of constructors
206 accepting it (wxCmdLineParser(int, char**) or
207 wxCmdLineParser(const wxString&) usually) or, if you use the default
208 constructor, you can do it later by calling SetCmdLine().
209
210 The same holds for command line description: it can be specified either in
211 the constructor (with or without the command line itself) or constructed
e559d790
VZ
212 later using either SetDesc() or combination of AddSwitch(), AddOption(),
213 AddParam() and AddUsageText() methods.
7c913512 214
d18d9f60
BP
215 Using constructors or SetDesc() uses a (usually const static) table
216 containing the command line description. If you want to decide which
217 options to accept during the run-time, using one of the AddXXX() functions
218 above might be preferable.
219
220
221 @section cmdlineparser_customization Customization
222
223 wxCmdLineParser has several global options which may be changed by the
224 application. All of the functions described in this section should be
225 called before Parse().
226
227 First global option is the support for long (also known as GNU-style)
228 options. The long options are the ones which start with two dashes and look
229 like "--verbose", i.e. they generally are complete words and not some
230 abbreviations of them. As long options are used by more and more
231 applications, they are enabled by default, but may be disabled with
232 DisableLongOptions().
233
234 Another global option is the set of characters which may be used to start
235 an option (otherwise, the word on the command line is assumed to be a
a15c16bf
VZ
236 parameter). Under Unix, @c "-" is always used, but Windows has at least two
237 common choices for this: @c "-" and @c "/". Some programs also use "+". The
d18d9f60
BP
238 default is to use what suits most the current platform, but may be changed
239 with SetSwitchChars() method.
240
241 Finally, SetLogo() can be used to show some application-specific text
242 before the explanation given by Usage() function.
243
244
245 @section cmdlineparser_parsing Parsing the Command Line
246
247 After the command line description was constructed and the desired options
248 were set, you can finally call Parse() method. It returns 0 if the command
249 line was correct and was parsed, -1 if the help option was specified (this
250 is a separate case as, normally, the program will terminate after this) or
251 a positive number if there was an error during the command line parsing.
252
253 In the latter case, the appropriate error message and usage information are
254 logged by wxCmdLineParser itself using the standard wxWidgets logging
255 functions.
256
257
258 @section cmdlineparser_results Getting Results
259
260 After calling Parse() (and if it returned 0), you may access the results of
261 parsing using one of overloaded Found() methods.
262
263 For a simple switch, you will simply call Found to determine if the switch
264 was given or not, for an option or a parameter, you will call a version of
265 Found() which also returns the associated value in the provided variable.
266 All Found() functions return true if the switch or option were found in the
267 command line or false if they were not specified.
7c913512
FM
268
269
23324ae1
FM
270 @library{wxbase}
271 @category{appmanagement}
7c913512 272
3d46a376 273 @see wxApp::argc, wxApp::argv, @ref page_samples_console
23324ae1 274*/
7c913512 275class wxCmdLineParser
23324ae1
FM
276{
277public:
23324ae1 278 /**
d18d9f60 279 Default constructor, you must use SetCmdLine() later.
23324ae1
FM
280 */
281 wxCmdLineParser();
d18d9f60 282
d18d9f60
BP
283 /**
284 Constructor which specifies the command line to parse. This is the
285 traditional (Unix) command line format. The parameters @a argc and
286 @a argv have the same meaning as the typical @c main() function.
287
3d46a376 288 This constructor is available in both ANSI and Unicode modes because under
d18d9f60
BP
289 some platforms the command line arguments are passed as ASCII strings
290 even to Unicode programs.
291 */
7c913512 292 wxCmdLineParser(int argc, char** argv);
3d46a376
FM
293
294 /**
295 Constructor which specifies the command line to parse.
296 This is the traditional (Unix) command line format.
297
298 The parameters @a argc and @a argv have the same meaning as the typical
299 @c main() function.
300
301 This constructor is only available in Unicode build.
302 */
7c913512 303 wxCmdLineParser(int argc, wchar_t** argv);
d18d9f60
BP
304
305 /**
306 Constructor which specify the command line to parse in Windows format.
307 The parameter cmdline has the same meaning as the corresponding
308 parameter of @c WinMain().
309 */
7c913512 310 wxCmdLineParser(const wxString& cmdline);
d18d9f60
BP
311
312 /**
313 Specifies the @ref SetDesc() "command line description" but not the
314 command line. You must use SetCmdLine() later.
315 */
7c913512 316 wxCmdLineParser(const wxCmdLineEntryDesc* desc);
d18d9f60
BP
317
318 /**
319 Specifies both the command line (in Unix format) and the
320 @ref SetDesc() "command line description".
321 */
a15c16bf 322 wxCmdLineParser(const wxCmdLineEntryDesc* desc, int argc, char** argv);
d18d9f60
BP
323
324 /**
325 Specifies both the command line (in Windows format) and the
326 @ref SetDesc() "command line description".
327 */
7c913512
FM
328 wxCmdLineParser(const wxCmdLineEntryDesc* desc,
329 const wxString& cmdline);
23324ae1
FM
330
331 /**
332 Frees resources allocated by the object.
d18d9f60
BP
333
334 @note This destructor is not virtual, don't use this class
335 polymorphically.
23324ae1
FM
336 */
337 ~wxCmdLineParser();
338
5f4994df
VZ
339 /**
340 Adds an option with only long form.
341
342 This is just a convenient wrapper for AddOption() passing an empty
343 string as short option name.
344
345 @since 2.9.3
346 */
347 void AddLongOption(const wxString& lng,
348 const wxString& desc = wxEmptyString,
349 wxCmdLineParamType type = wxCMD_LINE_VAL_STRING,
350 int flags = 0);
351
352 /**
353 Adds a switch with only long form.
354
355 This is just a convenient wrapper for AddSwitch() passing an empty
356 string as short switch name.
357
358 @since 2.9.3
359 */
360
361 void AddLongSwitch(const wxString& lng,
362 const wxString& desc = wxEmptyString,
363 int flags = 0);
364
23324ae1 365 /**
d18d9f60
BP
366 Add an option @a name with an optional long name @a lng (no long name
367 if it is empty, which is default) taking a value of the given type
368 (string by default) to the command line description.
23324ae1
FM
369 */
370 void AddOption(const wxString& name,
371 const wxString& lng = wxEmptyString,
372 const wxString& desc = wxEmptyString,
373 wxCmdLineParamType type = wxCMD_LINE_VAL_STRING,
374 int flags = 0);
375
376 /**
4cc4bfaf 377 Add a parameter of the given @a type to the command line description.
23324ae1
FM
378 */
379 void AddParam(const wxString& desc = wxEmptyString,
380 wxCmdLineParamType type = wxCMD_LINE_VAL_STRING,
381 int flags = 0);
382
383 /**
d18d9f60
BP
384 Add a switch @a name with an optional long name @a lng (no long name if
385 it is empty, which is default), description @a desc and flags @a flags
386 to the command line description.
23324ae1
FM
387 */
388 void AddSwitch(const wxString& name,
389 const wxString& lng = wxEmptyString,
390 const wxString& desc = wxEmptyString,
391 int flags = 0);
392
e559d790
VZ
393 /**
394 Add a string @a text to the command line description shown by Usage().
395
396 @since 2.9.0
397 */
398 void AddUsageText(const wxString& text);
399
23324ae1
FM
400 /**
401 Returns @true if long options are enabled, otherwise @false.
3c4f71cc 402
4cc4bfaf 403 @see EnableLongOptions()
23324ae1 404 */
779288b4 405 bool AreLongOptionsEnabled() const;
23324ae1
FM
406
407 /**
a4761b4c
VZ
408 Breaks down the string containing the full command line in words.
409
410 Words are separated by whitespace and double quotes can be used to
411 preserve the spaces inside the words.
412
413 By default, this function uses Windows-like word splitting algorithm,
414 i.e. single quotes have no special meaning and backslash can't be used
415 to escape spaces neither. With @c wxCMD_LINE_SPLIT_UNIX flag Unix
416 semantics is used, i.e. both single and double quotes can be used and
417 backslash can be used to escape all the other special characters.
23324ae1 418 */
a4761b4c 419 static wxArrayString
920b92a3 420 ConvertStringToArgs(const wxString& cmdline,
a4761b4c 421 wxCmdLineSplitType flags = wxCMD_LINE_SPLIT_DOS);
23324ae1
FM
422
423 /**
d18d9f60 424 Identical to EnableLongOptions(@false).
23324ae1 425 */
d18d9f60 426 void DisableLongOptions();
23324ae1
FM
427
428 /**
d18d9f60
BP
429 Enable or disable support for the long options.
430
431 As long options are not (yet) POSIX-compliant, this option allows to
432 disable them.
433
434 @see @ref cmdlineparser_customization and AreLongOptionsEnabled()
23324ae1 435 */
d18d9f60 436 void EnableLongOptions(bool enable = true);
23324ae1 437
d18d9f60
BP
438 /**
439 Returns @true if the given switch was found, @false otherwise.
440 */
441 bool Found(const wxString& name) const;
23324ae1 442
a6bf0c95
VZ
443 /**
444 Returns whether the switch was found on the command line and whether it
445 was negated.
446
447 This method can be used for any kind of switch but is especially useful
448 for switches that can be negated, i.e. were added with
449 wxCMD_LINE_SWITCH_NEGATABLE flag, as otherwise Found() is simpler to
450 use.
451
452 However Found() doesn't allow to distinguish between switch specified
453 normally, i.e. without dash following it, and negated switch, i.e. with
454 the following dash. This method will return @c wxCMD_SWITCH_ON or @c
455 wxCMD_SWITCH_OFF depending on whether the switch was negated or not.
456 And if the switch was not found at all, @c wxCMD_SWITCH_NOT_FOUND is
457 returned.
458
459 @since 2.9.2
460 */
461 wxCmdLineSwitchState FoundSwitch(const wxString& name) const;
462
23324ae1 463 /**
d18d9f60
BP
464 Returns true if an option taking a string value was found and stores
465 the value in the provided pointer (which should not be @NULL).
23324ae1 466 */
d18d9f60 467 bool Found(const wxString& name, wxString* value) const;
23324ae1
FM
468
469 /**
d18d9f60
BP
470 Returns @true if an option taking an integer value was found and stores
471 the value in the provided pointer (which should not be @NULL).
472 */
473 bool Found(const wxString& name, long* value) const;
3c4f71cc 474
d18d9f60
BP
475 /**
476 Returns @true if an option taking a float value was found and stores
477 the value in the provided pointer (which should not be @NULL).
23324ae1 478 */
d18d9f60 479 bool Found(const wxString& name, double* value) const;
23324ae1 480
23324ae1
FM
481 /**
482 Returns @true if an option taking a date value was found and stores the
483 value in the provided pointer (which should not be @NULL).
484 */
b1859b1a 485 bool Found(const wxString& name, wxDateTime* value) const;
23324ae1
FM
486
487 /**
488 Returns the value of Nth parameter (as string only).
489 */
d18d9f60 490 wxString GetParam(size_t n = 0) const;
23324ae1
FM
491
492 /**
d18d9f60
BP
493 Returns the number of parameters found. This function makes sense
494 mostly if you had used @c wxCMD_LINE_PARAM_MULTIPLE flag.
23324ae1 495 */
328f5751 496 size_t GetParamCount() const;
23324ae1 497
23324ae1 498 /**
7c913512 499 Parse the command line, return 0 if ok, -1 if @c "-h" or @c "--help"
d18d9f60
BP
500 option was encountered and the help message was given or a positive
501 value if a syntax error occurred.
3c4f71cc 502
7c913512 503 @param giveUsage
d18d9f60
BP
504 If @true (default), the usage message is given if a syntax error
505 was encountered while parsing the command line or if help was
506 requested. If @false, only error messages about possible syntax
507 errors are given, use Usage to show the usage message from the
508 caller if needed.
23324ae1 509 */
4cc4bfaf 510 int Parse(bool giveUsage = true);
23324ae1 511
23324ae1
FM
512 //@{
513 /**
d18d9f60
BP
514 Set the command line to parse after using one of the constructors which
515 don't do it.
23324ae1
FM
516 */
517 void SetCmdLine(int argc, char** argv);
7c913512
FM
518 void SetCmdLine(int argc, wchar_t** argv);
519 void SetCmdLine(const wxString& cmdline);
23324ae1
FM
520 //@}
521
522 /**
d18d9f60
BP
523 Constructs the command line description.
524
525 Take the command line description from the wxCMD_LINE_NONE terminated
526 table.
527
23324ae1 528 Example of usage:
d18d9f60
BP
529
530 @code
531 static const wxCmdLineEntryDesc cmdLineDesc[] =
532 {
533 { wxCMD_LINE_SWITCH, "v", "verbose", "be verbose" },
534 { wxCMD_LINE_SWITCH, "q", "quiet", "be quiet" },
535
536 { wxCMD_LINE_OPTION, "o", "output", "output file" },
537 { wxCMD_LINE_OPTION, "i", "input", "input dir" },
538 { wxCMD_LINE_OPTION, "s", "size", "output block size", wxCMD_LINE_VAL_NUMBER },
539 { wxCMD_LINE_OPTION, "d", "date", "output file date", wxCMD_LINE_VAL_DATE },
540
541 { wxCMD_LINE_PARAM, NULL, NULL, "input file", wxCMD_LINE_VAL_STRING, wxCMD_LINE_PARAM_MULTIPLE },
542
543 { wxCMD_LINE_NONE }
544 };
545
546 wxCmdLineParser parser;
547
548 parser.SetDesc(cmdLineDesc);
549 @endcode
23324ae1
FM
550 */
551 void SetDesc(const wxCmdLineEntryDesc* desc);
552
553 /**
d18d9f60 554 The @a logo is some extra text which will be shown by Usage() method.
23324ae1
FM
555 */
556 void SetLogo(const wxString& logo);
557
558 /**
d18d9f60
BP
559 @a switchChars contains all characters with which an option or switch
560 may start. Default is @c "-" for Unix, @c "-/" for Windows.
23324ae1
FM
561 */
562 void SetSwitchChars(const wxString& switchChars);
563
564 /**
d18d9f60
BP
565 Give the standard usage message describing all program options. It will
566 use the options and parameters descriptions specified earlier, so the
567 resulting message will not be helpful to the user unless the
568 descriptions were indeed specified.
3c4f71cc 569
4cc4bfaf 570 @see SetLogo()
23324ae1 571 */
779288b4 572 void Usage() const;
16b627b0
VZ
573
574 /**
575 Return the string containing the program usage description.
576
577 Call Usage() to directly show this string to the user.
578 */
579 wxString GetUsageString() const;
23324ae1 580};
e54c96f1 581