]>
Commit | Line | Data |
---|---|---|
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 | */ | |
34 | enum 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 | */ | |
48 | enum 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 | */ | |
60 | enum 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 | */ | |
83 | enum 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 | */ | |
99 | enum 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 | */ | |
113 | struct 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 | */ | |
274 | class wxCmdLineParser | |
275 | { | |
276 | public: | |
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 |