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         Add an option @a name with an optional long name @a lng (no long name
 341         if it is empty, which is default) taking a value of the given type
 342         (string by default) to the command line description.
 343     */
 344     void AddOption(const wxString& name,
 345                    const wxString& lng = wxEmptyString,
 346                    const wxString& desc = wxEmptyString,
 347                    wxCmdLineParamType type = wxCMD_LINE_VAL_STRING,
 348                    int flags = 0);
 349
 350     /**
 351         Add a parameter of the given @a type to the command line description.
 352     */
 353     void AddParam(const wxString& desc = wxEmptyString,
 354                   wxCmdLineParamType type = wxCMD_LINE_VAL_STRING,
 355                   int flags = 0);
 356
 357     /**
 358         Add a switch @a name with an optional long name @a lng (no long name if
 359         it is empty, which is default), description @a desc and flags @a flags
 360         to the command line description.
 361     */
 362     void AddSwitch(const wxString& name,
 363                    const wxString& lng = wxEmptyString,
 364                    const wxString& desc = wxEmptyString,
 365                    int flags = 0);
 366
 367     /**
 368         Add a string @a text to the command line description shown by Usage().
 369
 370         @since 2.9.0
 371     */
 372     void AddUsageText(const wxString& text);
 373
 374     /**
 375         Returns @true if long options are enabled, otherwise @false.
 376
 377         @see EnableLongOptions()
 378     */
 379     bool AreLongOptionsEnabled() const;
 380
 381     /**
 382         Breaks down the string containing the full command line in words.
 383
 384         Words are separated by whitespace and double quotes can be used to
 385         preserve the spaces inside the words.
 386
 387         By default, this function uses Windows-like word splitting algorithm,
 388         i.e. single quotes have no special meaning and backslash can't be used
 389         to escape spaces neither. With @c wxCMD_LINE_SPLIT_UNIX flag Unix
 390         semantics is used, i.e. both single and double quotes can be used and
 391         backslash can be used to escape all the other special characters.
 392     */
 393     static wxArrayString
 394     ConvertStringToArgs(const wxString& cmdline,
 395                         wxCmdLineSplitType flags = wxCMD_LINE_SPLIT_DOS);
 396
 397     /**
 398         Identical to EnableLongOptions(@false).
 399     */
 400     void DisableLongOptions();
 401
 402     /**
 403         Enable or disable support for the long options.
 404
 405         As long options are not (yet) POSIX-compliant, this option allows to
 406         disable them.
 407
 408         @see @ref cmdlineparser_customization and AreLongOptionsEnabled()
 409     */
 410     void EnableLongOptions(bool enable = true);
 411
 412     /**
 413         Returns @true if the given switch was found, @false otherwise.
 414     */
 415     bool Found(const wxString& name) const;
 416
 417     /**
 418         Returns whether the switch was found on the command line and whether it
 419         was negated.
 420
 421         This method can be used for any kind of switch but is especially useful
 422         for switches that can be negated, i.e. were added with
 423         wxCMD_LINE_SWITCH_NEGATABLE flag, as otherwise Found() is simpler to
 424         use.
 425
 426         However Found() doesn't allow to distinguish between switch specified
 427         normally, i.e. without dash following it, and negated switch, i.e. with
 428         the following dash. This method will return @c wxCMD_SWITCH_ON or @c
 429         wxCMD_SWITCH_OFF depending on whether the switch was negated or not.
 430         And if the switch was not found at all, @c wxCMD_SWITCH_NOT_FOUND is
 431         returned.
 432
 433         @since 2.9.2
 434     */
 435     wxCmdLineSwitchState FoundSwitch(const wxString& name) const;
 436
 437     /**
 438         Returns true if an option taking a string value was found and stores
 439         the value in the provided pointer (which should not be @NULL).
 440     */
 441     bool Found(const wxString& name, wxString* value) const;
 442
 443     /**
 444         Returns @true if an option taking an integer value was found and stores
 445         the value in the provided pointer (which should not be @NULL).
 446     */
 447     bool Found(const wxString& name, long* value) const;
 448
 449     /**
 450         Returns @true if an option taking a float value was found and stores
 451         the value in the provided pointer (which should not be @NULL).
 452     */
 453     bool Found(const wxString& name, double* value) const;
 454
 455     /**
 456         Returns @true if an option taking a date value was found and stores the
 457         value in the provided pointer (which should not be @NULL).
 458     */
 459     bool Found(const wxString& name, wxDateTime* value) const;
 460
 461     /**
 462         Returns the value of Nth parameter (as string only).
 463     */
 464     wxString GetParam(size_t n = 0) const;
 465
 466     /**
 467         Returns the number of parameters found. This function makes sense
 468         mostly if you had used @c wxCMD_LINE_PARAM_MULTIPLE flag.
 469     */
 470     size_t GetParamCount() const;
 471
 472     /**
 473         Parse the command line, return 0 if ok, -1 if @c "-h" or @c "--help"
 474         option was encountered and the help message was given or a positive
 475         value if a syntax error occurred.
 476
 477         @param giveUsage
 478             If @true (default), the usage message is given if a syntax error
 479             was encountered while parsing the command line or if help was
 480             requested. If @false, only error messages about possible syntax
 481             errors are given, use Usage to show the usage message from the
 482             caller if needed.
 483     */
 484     int Parse(bool giveUsage = true);
 485
 486     //@{
 487     /**
 488         Set the command line to parse after using one of the constructors which
 489         don't do it.
 490     */
 491     void SetCmdLine(int argc, char** argv);
 492     void SetCmdLine(int argc, wchar_t** argv);
 493     void SetCmdLine(const wxString& cmdline);
 494     //@}
 495
 496     /**
 497         Constructs the command line description.
 498
 499         Take the command line description from the wxCMD_LINE_NONE terminated
 500         table.
 501
 502         Example of usage:
 503
 504         @code
 505         static const wxCmdLineEntryDesc cmdLineDesc[] =
 506         {
 507             { wxCMD_LINE_SWITCH, "v", "verbose", "be verbose" },
 508             { wxCMD_LINE_SWITCH, "q", "quiet",   "be quiet" },
 509
 510             { wxCMD_LINE_OPTION, "o", "output",  "output file" },
 511             { wxCMD_LINE_OPTION, "i", "input",   "input dir" },
 512             { wxCMD_LINE_OPTION, "s", "size",    "output block size", wxCMD_LINE_VAL_NUMBER },
 513             { wxCMD_LINE_OPTION, "d", "date",    "output file date", wxCMD_LINE_VAL_DATE },
 514
 515             { wxCMD_LINE_PARAM,  NULL, NULL, "input file", wxCMD_LINE_VAL_STRING, wxCMD_LINE_PARAM_MULTIPLE },
 516
 517             { wxCMD_LINE_NONE }
 518         };
 519
 520         wxCmdLineParser parser;
 521
 522         parser.SetDesc(cmdLineDesc);
 523         @endcode
 524     */
 525     void SetDesc(const wxCmdLineEntryDesc* desc);
 526
 527     /**
 528         The @a logo is some extra text which will be shown by Usage() method.
 529     */
 530     void SetLogo(const wxString& logo);
 531
 532     /**
 533         @a switchChars contains all characters with which an option or switch
 534         may start. Default is @c "-" for Unix, @c "-/" for Windows.
 535     */
 536     void SetSwitchChars(const wxString& switchChars);
 537
 538     /**
 539         Give the standard usage message describing all program options. It will
 540         use the options and parameters descriptions specified earlier, so the
 541         resulting message will not be helpful to the user unless the
 542         descriptions were indeed specified.
 543
 544         @see SetLogo()
 545     */
 546     void Usage() const;
 547
 548     /**
 549         Return the string containing the program usage description.
 550
 551         Call Usage() to directly show this string to the user.
 552      */
 553     wxString GetUsageString() const;
 554 };
 555