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