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