]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/cmdline.h
put both versions of wxGetMousePosition in one place so they can use one implementation
[wxWidgets.git] / interface / wx / cmdline.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: cmdline.h
3 // Purpose: interface of wxCmdLineParser
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
8
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
13 (sic) and each call to wxCmdLineParser::AddParam() allows one more
14 parameter - this may be changed by giving non-default flags to it, i.e. use
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
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
25 @c wxCMD_LINE_NEEDS_SEPARATOR can be specified to require a separator (either
26 a colon, an equal sign or white space) between the option name and its
27 value. By default, no separator is required.
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.
34 */
35 enum wxCmdLineEntryFlags
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.
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-)
43 };
44
45 /**
46 The possible values of wxCmdLineEntryDesc::type which specify the type of
47 the value accepted by an option.
48 */
49 enum 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 */
61 enum wxCmdLineEntryType
62 {
63 /// A boolean argument of the program; e.g. @c -v to enable verbose mode.
64 wxCMD_LINE_SWITCH,
65
66 /// An argument with an associated value; e.g. @c "-o filename" to specify
67 /// an optional output filename.
68 wxCMD_LINE_OPTION,
69
70 /// A parameter: a required program argument.
71 wxCMD_LINE_PARAM,
72
73 /// Additional usage text. See wxCmdLineParser::AddUsageText.
74 wxCMD_LINE_USAGE_TEXT,
75
76 wxCMD_LINE_NONE ///< Use this to terminate the list.
77 };
78
79 /**
80 The state of a switch as returned by wxCmdLineParser::FoundSwitch().
81
82 @since 2.9.2
83 */
84 enum 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
97 /**
98 Flags determining wxCmdLineParser::ConvertStringToArgs() behaviour.
99 */
100 enum wxCmdLineSplitType
101 {
102 wxCMD_LINE_SPLIT_DOS,
103 wxCMD_LINE_SPLIT_UNIX
104 };
105
106 /**
107 The structure wxCmdLineEntryDesc is used to describe a command line
108 switch, option or parameter. An array of such structures should be passed
109 to wxCmdLineParser::SetDesc().
110
111 Note that the meanings of parameters of the wxCmdLineParser::AddXXX() functions
112 are the same as of the corresponding fields in this structure.
113 */
114 struct wxCmdLineEntryDesc
115 {
116 /**
117 The kind of this program argument.
118 See ::wxCmdLineEntryType for more info.
119 */
120 wxCmdLineEntryType kind;
121
122 /**
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>.
127 */
128 const char *shortName;
129
130 /**
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>.
136 */
137 const char *longName;
138
139 /**
140 This description is used by the wxCmdLineParser::Usage() method to
141 construct a help message explaining the syntax of the program.
142 */
143 const char *description;
144
145 /**
146 The type associated with this option (ignored if <tt>kind != wxCMD_LINE_OPTION</tt>).
147 See ::wxCmdLineParamType for more info.
148 */
149 wxCmdLineParamType type;
150
151 /**
152 A combination of one or more ::wxCmdLineEntryFlags enum values.
153 */
154 int flags;
155 };
156
157 /**
158 @class wxCmdLineParser
159
160 wxCmdLineParser is a class for parsing the command line.
161
162 It has the following features:
163
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, ...).
169
170 To use it you should follow these steps:
171
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.
177
178 You can also use wxApp's default command line processing just overriding
179 wxAppConsole::OnInitCmdLine() and wxAppConsole::OnCmdLineParsed().
180
181 In the documentation below the following terminology is used:
182
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
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".
188 - @b option: a switch with a value associated to it.
189 For example, @c "-o filename" might be an
190 option for specifying the name of the output file.
191 - @b parameter: a required program argument.
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
212 later using either SetDesc() or combination of AddSwitch(), AddOption(),
213 AddParam() and AddUsageText() methods.
214
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
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
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.
268
269
270 @library{wxbase}
271 @category{appmanagement}
272
273 @see wxApp::argc, wxApp::argv, @ref page_samples_console
274 */
275 class wxCmdLineParser
276 {
277 public:
278 /**
279 Default constructor, you must use SetCmdLine() later.
280 */
281 wxCmdLineParser();
282
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
288 This constructor is available in both ANSI and Unicode modes because under
289 some platforms the command line arguments are passed as ASCII strings
290 even to Unicode programs.
291 */
292 wxCmdLineParser(int argc, char** argv);
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 */
303 wxCmdLineParser(int argc, wchar_t** argv);
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 */
310 wxCmdLineParser(const wxString& cmdline);
311
312 /**
313 Specifies the @ref SetDesc() "command line description" but not the
314 command line. You must use SetCmdLine() later.
315 */
316 wxCmdLineParser(const wxCmdLineEntryDesc* desc);
317
318 /**
319 Specifies both the command line (in Unix format) and the
320 @ref SetDesc() "command line description".
321 */
322 wxCmdLineParser(const wxCmdLineEntryDesc* desc, int argc, char** argv);
323
324 /**
325 Specifies both the command line (in Windows format) and the
326 @ref SetDesc() "command line description".
327 */
328 wxCmdLineParser(const wxCmdLineEntryDesc* desc,
329 const wxString& cmdline);
330
331 /**
332 Frees resources allocated by the object.
333
334 @note This destructor is not virtual, don't use this class
335 polymorphically.
336 */
337 ~wxCmdLineParser();
338
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
365 /**
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.
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 /**
377 Add a parameter of the given @a type to the command line description.
378 */
379 void AddParam(const wxString& desc = wxEmptyString,
380 wxCmdLineParamType type = wxCMD_LINE_VAL_STRING,
381 int flags = 0);
382
383 /**
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.
387 */
388 void AddSwitch(const wxString& name,
389 const wxString& lng = wxEmptyString,
390 const wxString& desc = wxEmptyString,
391 int flags = 0);
392
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
400 /**
401 Returns @true if long options are enabled, otherwise @false.
402
403 @see EnableLongOptions()
404 */
405 bool AreLongOptionsEnabled() const;
406
407 /**
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.
418 */
419 static wxArrayString
420 ConvertStringToArgs(const wxString& cmdline,
421 wxCmdLineSplitType flags = wxCMD_LINE_SPLIT_DOS);
422
423 /**
424 Identical to EnableLongOptions(@false).
425 */
426 void DisableLongOptions();
427
428 /**
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()
435 */
436 void EnableLongOptions(bool enable = true);
437
438 /**
439 Returns @true if the given switch was found, @false otherwise.
440 */
441 bool Found(const wxString& name) const;
442
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
463 /**
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).
466 */
467 bool Found(const wxString& name, wxString* value) const;
468
469 /**
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;
474
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).
478 */
479 bool Found(const wxString& name, double* value) const;
480
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 */
485 bool Found(const wxString& name, wxDateTime* value) const;
486
487 /**
488 Returns the value of Nth parameter (as string only).
489 */
490 wxString GetParam(size_t n = 0) const;
491
492 /**
493 Returns the number of parameters found. This function makes sense
494 mostly if you had used @c wxCMD_LINE_PARAM_MULTIPLE flag.
495 */
496 size_t GetParamCount() const;
497
498 /**
499 Parse the command line, return 0 if ok, -1 if @c "-h" or @c "--help"
500 option was encountered and the help message was given or a positive
501 value if a syntax error occurred.
502
503 @param giveUsage
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.
509 */
510 int Parse(bool giveUsage = true);
511
512 //@{
513 /**
514 Set the command line to parse after using one of the constructors which
515 don't do it.
516 */
517 void SetCmdLine(int argc, char** argv);
518 void SetCmdLine(int argc, wchar_t** argv);
519 void SetCmdLine(const wxString& cmdline);
520 //@}
521
522 /**
523 Constructs the command line description.
524
525 Take the command line description from the wxCMD_LINE_NONE terminated
526 table.
527
528 Example of usage:
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
550 */
551 void SetDesc(const wxCmdLineEntryDesc* desc);
552
553 /**
554 The @a logo is some extra text which will be shown by Usage() method.
555 */
556 void SetLogo(const wxString& logo);
557
558 /**
559 @a switchChars contains all characters with which an option or switch
560 may start. Default is @c "-" for Unix, @c "-/" for Windows.
561 */
562 void SetSwitchChars(const wxString& switchChars);
563
564 /**
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.
569
570 @see SetLogo()
571 */
572 void Usage() const;
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;
580 };
581