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_NONE     ///< Use this to terminate the list.
  59 };
  60
  61 /**
  62     The structure wxCmdLineEntryDesc is used to describe the one command line
  63     switch, option or parameter. An array of such structures should be passed
  64     to wxCmdLineParser::SetDesc(). Also, the meanings of parameters of the
  65     wxCmdLineParser::AddXXX() functions are the same as of the corresponding
  66     fields in this structure.
  67
  68     The field @c shortName is the usual, short, name of the switch or the
  69     option. @c longName is the corresponding long name or empty if the option
  70     has no long name. Both of these fields are unused for the parameters. Both
  71     the short and long option names can contain only letters, digits and the
  72     underscores.
  73
  74     @c description is used by the wxCmdLineEntryDesc::Usage() method to
  75     construct a help message explaining the syntax of the program.
  76 */
  77 struct wxCmdLineEntryDesc
  78 {
  79     wxCmdLineEntryType kind;
  80     const char *shortName;
  81     const char *longName;
  82     const char *description;
  83     wxCmdLineParamType type;
  84     int flags;
  85 };
  86
  87 /**
  88     @class wxCmdLineParser
  89     @wxheader{cmdline.h}
  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:filename might be an
 118                  option for specifing the name of the output file.
 119     - @b parameter: This is a required program argument.
 120
 121
 122     @section cmdlineparser_construction Construction
 123
 124     Before Parse() can be called, the command line parser object must have the
 125     command line to parse and also the rules saying which switches, options and
 126     parameters are valid - this is called command line description in what
 127     follows.
 128
 129     You have complete freedom of choice as to when specify the required
 130     information, the only restriction is that it must be done before calling
 131     Parse().
 132
 133     To specify the command line to parse you may use either one of constructors
 134     accepting it (wxCmdLineParser(int, char**) or
 135     wxCmdLineParser(const wxString&) usually) or, if you use the default
 136     constructor, you can do it later by calling SetCmdLine().
 137
 138     The same holds for command line description: it can be specified either in
 139     the constructor (with or without the command line itself) or constructed
 140     later using either SetDesc() or combination of AddSwitch(), AddOption() and
 141     AddParam() methods.
 142
 143     Using constructors or SetDesc() uses a (usually const static) table
 144     containing the command line description. If you want to decide which
 145     options to accept during the run-time, using one of the AddXXX() functions
 146     above might be preferable.
 147
 148
 149     @section cmdlineparser_customization Customization
 150
 151     wxCmdLineParser has several global options which may be changed by the
 152     application. All of the functions described in this section should be
 153     called before Parse().
 154
 155     First global option is the support for long (also known as GNU-style)
 156     options. The long options are the ones which start with two dashes and look
 157     like "--verbose", i.e. they generally are complete words and not some
 158     abbreviations of them. As long options are used by more and more
 159     applications, they are enabled by default, but may be disabled with
 160     DisableLongOptions().
 161
 162     Another global option is the set of characters which may be used to start
 163     an option (otherwise, the word on the command line is assumed to be a
 164     parameter). Under Unix, "-" is always used, but Windows has at least two
 165     common choices for this: "-" and "/". Some programs also use "+". The
 166     default is to use what suits most the current platform, but may be changed
 167     with SetSwitchChars() method.
 168
 169     Finally, SetLogo() can be used to show some application-specific text
 170     before the explanation given by Usage() function.
 171
 172
 173     @section cmdlineparser_parsing Parsing the Command Line
 174
 175     After the command line description was constructed and the desired options
 176     were set, you can finally call Parse() method. It returns 0 if the command
 177     line was correct and was parsed, -1 if the help option was specified (this
 178     is a separate case as, normally, the program will terminate after this) or
 179     a positive number if there was an error during the command line parsing.
 180
 181     In the latter case, the appropriate error message and usage information are
 182     logged by wxCmdLineParser itself using the standard wxWidgets logging
 183     functions.
 184
 185
 186     @section cmdlineparser_results Getting Results
 187
 188     After calling Parse() (and if it returned 0), you may access the results of
 189     parsing using one of overloaded Found() methods.
 190
 191     For a simple switch, you will simply call Found to determine if the switch
 192     was given or not, for an option or a parameter, you will call a version of
 193     Found() which also returns the associated value in the provided variable.
 194     All Found() functions return true if the switch or option were found in the
 195     command line or false if they were not specified.
 196
 197
 198     @library{wxbase}
 199     @category{appmanagement}
 200
 201     @see wxApp::argc, wxApp::argv, @ref page_samples_console "Console Sample"
 202 */
 203 class wxCmdLineParser
 204 {
 205 public:
 206     /**
 207         Default constructor, you must use SetCmdLine() later.
 208     */
 209     wxCmdLineParser();
 210
 211     //@{
 212     /**
 213         Constructor which specifies the command line to parse. This is the
 214         traditional (Unix) command line format. The parameters @a argc and
 215         @a argv have the same meaning as the typical @c main() function.
 216
 217         The second overloaded constructor is only available in Unicode build.
 218         The first one is available in both ANSI and Unicode modes because under
 219         some platforms the command line arguments are passed as ASCII strings
 220         even to Unicode programs.
 221     */
 222     wxCmdLineParser(int argc, char** argv);
 223     wxCmdLineParser(int argc, wchar_t** argv);
 224     //@}
 225
 226     /**
 227         Constructor which specify the command line to parse in Windows format.
 228         The parameter cmdline has the same meaning as the corresponding
 229         parameter of @c WinMain().
 230     */
 231     wxCmdLineParser(const wxString& cmdline);
 232
 233     /**
 234         Specifies the @ref SetDesc() "command line description" but not the
 235         command line. You must use SetCmdLine() later.
 236     */
 237     wxCmdLineParser(const wxCmdLineEntryDesc* desc);
 238
 239     /**
 240         Specifies both the command line (in Unix format) and the
 241         @ref SetDesc() "command line description".
 242     */
 243     wxCmdLineParser(const wxCmdLineEntryDesc* desc, int argc,
 244                     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         Returns @true if long options are enabled, otherwise @false.
 291
 292         @see EnableLongOptions()
 293     */
 294     bool AreLongOptionsEnabled() const;
 295
 296     /**
 297         Breaks down the string containing the full command line in words. The
 298         words are separated by whitespace. The quotes can be used in the input
 299         string to quote the white space and the back slashes can be used to
 300         quote the quotes.
 301     */
 302     static wxArrayString ConvertStringToArgs(const wxChar cmdline);
 303
 304     /**
 305         Identical to EnableLongOptions(@false).
 306     */
 307     void DisableLongOptions();
 308
 309     /**
 310         Enable or disable support for the long options.
 311
 312         As long options are not (yet) POSIX-compliant, this option allows to
 313         disable them.
 314
 315         @see @ref cmdlineparser_customization and AreLongOptionsEnabled()
 316     */
 317     void EnableLongOptions(bool enable = true);
 318
 319     /**
 320         Returns @true if the given switch was found, @false otherwise.
 321     */
 322     bool Found(const wxString& name) const;
 323
 324     /**
 325         Returns true if an option taking a string value was found and stores
 326         the value in the provided pointer (which should not be @NULL).
 327     */
 328     bool Found(const wxString& name, wxString* value) const;
 329
 330     /**
 331         Returns @true if an option taking an integer value was found and stores
 332         the value in the provided pointer (which should not be @NULL).
 333     */
 334     bool Found(const wxString& name, long* value) const;
 335
 336     /**
 337         Returns @true if an option taking a float value was found and stores
 338         the value in the provided pointer (which should not be @NULL).
 339     */
 340     bool Found(const wxString& name, double* value) const;
 341
 342     /**
 343         Returns @true if an option taking a date value was found and stores the
 344         value in the provided pointer (which should not be @NULL).
 345     */
 346     bool Found(const wxString& name, wxDateTime* value) const;
 347
 348     /**
 349         Returns the value of Nth parameter (as string only).
 350     */
 351     wxString GetParam(size_t n = 0) const;
 352
 353     /**
 354         Returns the number of parameters found. This function makes sense
 355         mostly if you had used @c wxCMD_LINE_PARAM_MULTIPLE flag.
 356     */
 357     size_t GetParamCount() const;
 358
 359     /**
 360         Parse the command line, return 0 if ok, -1 if @c "-h" or @c "--help"
 361         option was encountered and the help message was given or a positive
 362         value if a syntax error occurred.
 363
 364         @param giveUsage
 365             If @true (default), the usage message is given if a syntax error
 366             was encountered while parsing the command line or if help was
 367             requested. If @false, only error messages about possible syntax
 368             errors are given, use Usage to show the usage message from the
 369             caller if needed.
 370     */
 371     int Parse(bool giveUsage = true);
 372
 373     //@{
 374     /**
 375         Set the command line to parse after using one of the constructors which
 376         don't do it.
 377     */
 378     void SetCmdLine(int argc, char** argv);
 379     void SetCmdLine(int argc, wchar_t** argv);
 380     void SetCmdLine(const wxString& cmdline);
 381     //@}
 382
 383     /**
 384         Constructs the command line description.
 385
 386         Take the command line description from the wxCMD_LINE_NONE terminated
 387         table.
 388
 389         Example of usage:
 390
 391         @code
 392         static const wxCmdLineEntryDesc cmdLineDesc[] =
 393         {
 394             { wxCMD_LINE_SWITCH, "v", "verbose", "be verbose" },
 395             { wxCMD_LINE_SWITCH, "q", "quiet",   "be quiet" },
 396
 397             { wxCMD_LINE_OPTION, "o", "output",  "output file" },
 398             { wxCMD_LINE_OPTION, "i", "input",   "input dir" },
 399             { wxCMD_LINE_OPTION, "s", "size",    "output block size", wxCMD_LINE_VAL_NUMBER },
 400             { wxCMD_LINE_OPTION, "d", "date",    "output file date", wxCMD_LINE_VAL_DATE },
 401
 402             { wxCMD_LINE_PARAM,  NULL, NULL, "input file", wxCMD_LINE_VAL_STRING, wxCMD_LINE_PARAM_MULTIPLE },
 403
 404             { wxCMD_LINE_NONE }
 405         };
 406
 407         wxCmdLineParser parser;
 408
 409         parser.SetDesc(cmdLineDesc);
 410         @endcode
 411     */
 412     void SetDesc(const wxCmdLineEntryDesc* desc);
 413
 414     /**
 415         The @a logo is some extra text which will be shown by Usage() method.
 416     */
 417     void SetLogo(const wxString& logo);
 418
 419     /**
 420         @a switchChars contains all characters with which an option or switch
 421         may start. Default is @c "-" for Unix, @c "-/" for Windows.
 422     */
 423     void SetSwitchChars(const wxString& switchChars);
 424
 425     /**
 426         Give the standard usage message describing all program options. It will
 427         use the options and parameters descriptions specified earlier, so the
 428         resulting message will not be helpful to the user unless the
 429         descriptions were indeed specified.
 430
 431         @see SetLogo()
 432     */
 433     void Usage() const;
 434 };
 435