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