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