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