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: @c filename might be an
 118                  option for specifying 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, @c "-" is always used, but Windows has at least two
 165     common choices for this: @c "-" and @c "/". 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, char** argv);
 244
 245     /**
 246         Specifies both the command line (in Windows format) and the
 247         @ref SetDesc() "command line description".
 248     */
 249     wxCmdLineParser(const wxCmdLineEntryDesc* desc,
 250                     const wxString& cmdline);
 251
 252     /**
 253         Frees resources allocated by the object.
 254
 255         @note This destructor is not virtual, don't use this class
 256               polymorphically.
 257     */
 258     ~wxCmdLineParser();
 259
 260     /**
 261         Add an option @a name with an optional long name @a lng (no long name
 262         if it is empty, which is default) taking a value of the given type
 263         (string by default) to the command line description.
 264     */
 265     void AddOption(const wxString& name,
 266                    const wxString& lng = wxEmptyString,
 267                    const wxString& desc = wxEmptyString,
 268                    wxCmdLineParamType type = wxCMD_LINE_VAL_STRING,
 269                    int flags = 0);
 270
 271     /**
 272         Add a parameter of the given @a type to the command line description.
 273     */
 274     void AddParam(const wxString& desc = wxEmptyString,
 275                   wxCmdLineParamType type = wxCMD_LINE_VAL_STRING,
 276                   int flags = 0);
 277
 278     /**
 279         Add a switch @a name with an optional long name @a lng (no long name if
 280         it is empty, which is default), description @a desc and flags @a flags
 281         to the command line description.
 282     */
 283     void AddSwitch(const wxString& name,
 284                    const wxString& lng = wxEmptyString,
 285                    const wxString& desc = wxEmptyString,
 286                    int flags = 0);
 287
 288     /**
 289         Returns @true if long options are enabled, otherwise @false.
 290
 291         @see EnableLongOptions()
 292     */
 293     bool AreLongOptionsEnabled() const;
 294
 295     /**
 296         Breaks down the string containing the full command line in words. The
 297         words are separated by whitespace. The quotes can be used in the input
 298         string to quote the white space and the back slashes can be used to
 299         quote the quotes.
 300     */
 301     static wxArrayString ConvertStringToArgs(const wxChar cmdline);
 302
 303     /**
 304         Identical to EnableLongOptions(@false).
 305     */
 306     void DisableLongOptions();
 307
 308     /**
 309         Enable or disable support for the long options.
 310
 311         As long options are not (yet) POSIX-compliant, this option allows to
 312         disable them.
 313
 314         @see @ref cmdlineparser_customization and AreLongOptionsEnabled()
 315     */
 316     void EnableLongOptions(bool enable = true);
 317
 318     /**
 319         Returns @true if the given switch was found, @false otherwise.
 320     */
 321     bool Found(const wxString& name) const;
 322
 323     /**
 324         Returns true if an option taking a string value was found and stores
 325         the value in the provided pointer (which should not be @NULL).
 326     */
 327     bool Found(const wxString& name, wxString* value) const;
 328
 329     /**
 330         Returns @true if an option taking an integer value was found and stores
 331         the value in the provided pointer (which should not be @NULL).
 332     */
 333     bool Found(const wxString& name, long* value) const;
 334
 335     /**
 336         Returns @true if an option taking a float value was found and stores
 337         the value in the provided pointer (which should not be @NULL).
 338     */
 339     bool Found(const wxString& name, double* value) const;
 340
 341     /**
 342         Returns @true if an option taking a date value was found and stores the
 343         value in the provided pointer (which should not be @NULL).
 344     */
 345     bool Found(const wxString& name, wxDateTime* value) const;
 346
 347     /**
 348         Returns the value of Nth parameter (as string only).
 349     */
 350     wxString GetParam(size_t n = 0) const;
 351
 352     /**
 353         Returns the number of parameters found. This function makes sense
 354         mostly if you had used @c wxCMD_LINE_PARAM_MULTIPLE flag.
 355     */
 356     size_t GetParamCount() const;
 357
 358     /**
 359         Parse the command line, return 0 if ok, -1 if @c "-h" or @c "--help"
 360         option was encountered and the help message was given or a positive
 361         value if a syntax error occurred.
 362
 363         @param giveUsage
 364             If @true (default), the usage message is given if a syntax error
 365             was encountered while parsing the command line or if help was
 366             requested. If @false, only error messages about possible syntax
 367             errors are given, use Usage to show the usage message from the
 368             caller if needed.
 369     */
 370     int Parse(bool giveUsage = true);
 371
 372     //@{
 373     /**
 374         Set the command line to parse after using one of the constructors which
 375         don't do it.
 376     */
 377     void SetCmdLine(int argc, char** argv);
 378     void SetCmdLine(int argc, wchar_t** argv);
 379     void SetCmdLine(const wxString& cmdline);
 380     //@}
 381
 382     /**
 383         Constructs the command line description.
 384
 385         Take the command line description from the wxCMD_LINE_NONE terminated
 386         table.
 387
 388         Example of usage:
 389
 390         @code
 391         static const wxCmdLineEntryDesc cmdLineDesc[] =
 392         {
 393             { wxCMD_LINE_SWITCH, "v", "verbose", "be verbose" },
 394             { wxCMD_LINE_SWITCH, "q", "quiet",   "be quiet" },
 395
 396             { wxCMD_LINE_OPTION, "o", "output",  "output file" },
 397             { wxCMD_LINE_OPTION, "i", "input",   "input dir" },
 398             { wxCMD_LINE_OPTION, "s", "size",    "output block size", wxCMD_LINE_VAL_NUMBER },
 399             { wxCMD_LINE_OPTION, "d", "date",    "output file date", wxCMD_LINE_VAL_DATE },
 400
 401             { wxCMD_LINE_PARAM,  NULL, NULL, "input file", wxCMD_LINE_VAL_STRING, wxCMD_LINE_PARAM_MULTIPLE },
 402
 403             { wxCMD_LINE_NONE }
 404         };
 405
 406         wxCmdLineParser parser;
 407
 408         parser.SetDesc(cmdLineDesc);
 409         @endcode
 410     */
 411     void SetDesc(const wxCmdLineEntryDesc* desc);
 412
 413     /**
 414         The @a logo is some extra text which will be shown by Usage() method.
 415     */
 416     void SetLogo(const wxString& logo);
 417
 418     /**
 419         @a switchChars contains all characters with which an option or switch
 420         may start. Default is @c "-" for Unix, @c "-/" for Windows.
 421     */
 422     void SetSwitchChars(const wxString& switchChars);
 423
 424     /**
 425         Give the standard usage message describing all program options. It will
 426         use the options and parameters descriptions specified earlier, so the
 427         resulting message will not be helpful to the user unless the
 428         descriptions were indeed specified.
 429
 430         @see SetLogo()
 431     */
 432     void Usage() const;
 433 };
 434