interface/wx/cmdline.h

   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