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