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