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