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     @class wxCmdLineParser
  11     @wxheader{cmdline.h}
  12
  13     wxCmdLineParser is a class for parsing the command line.
  14
  15     It has the following features:
  16
  17     - distinguishes options, switches and parameters
  18     - allows option grouping
  19     - allows both short and long options
  20     - automatically generates the usage message from the command line description
  21     - checks types of the options values (number, date, ...).
  22
  23     To use it you should follow these steps:
  24
  25     -# @ref wxCmdLineParser::construction construct an object of this class
  26     giving it the command line to parse and optionally its description or use
  27     @c AddXXX() functions later
  28     -# call @c Parse()
  29     -# use @c Found() to retrieve the results
  30
  31     In the documentation below the following terminology is used:
  32
  33     - @e switch
  34     This is a boolean option which can be given or not, but
  35     which doesn't have any value. We use the word switch to distinguish such boolean
  36     options from more generic options like those described below. For example,
  37     @c -v might be a switch meaning "enable verbose mode".
  38     - @e option
  39     Option for us here is something which comes with a value 0
  40     unlike a switch. For example, @c -o:filename might be an option which allows
  41     to specify the name of the output file.
  42     - @e parameter
  43     This is a required program argument.
  44
  45
  46
  47     @library{wxbase}
  48     @category{appmanagement}
  49
  50     @see wxApp::argc and wxApp::argv, console sample
  51 */
  52 class wxCmdLineParser
  53 {
  54 public:
  55     //@{
  56     /**
  57         Specifies both the command line (in Windows format) and the
  58         @ref setdesc() "command line description".
  59     */
  60     wxCmdLineParser();
  61     wxCmdLineParser(int argc, char** argv);
  62     wxCmdLineParser(int argc, wchar_t** argv);
  63     wxCmdLineParser(const wxString& cmdline);
  64     wxCmdLineParser(const wxCmdLineEntryDesc* desc);
  65     wxCmdLineParser(const wxCmdLineEntryDesc* desc, int argc,
  66                     char** argv);
  67     wxCmdLineParser(const wxCmdLineEntryDesc* desc,
  68                     const wxString& cmdline);
  69     //@}
  70
  71     /**
  72         Frees resources allocated by the object.
  73         @b NB: destructor is not virtual, don't use this class polymorphically.
  74     */
  75     ~wxCmdLineParser();
  76
  77     /**
  78         Add an option @a name with an optional long name @a lng (no long name if
  79         it is empty, which is default) taking a value of the given type (string by
  80         default) to the command line description.
  81     */
  82     void AddOption(const wxString& name,
  83                    const wxString& lng = wxEmptyString,
  84                    const wxString& desc = wxEmptyString,
  85                    wxCmdLineParamType type = wxCMD_LINE_VAL_STRING,
  86                    int flags = 0);
  87
  88     /**
  89         Add a parameter of the given @a type to the command line description.
  90     */
  91     void AddParam(const wxString& desc = wxEmptyString,
  92                   wxCmdLineParamType type = wxCMD_LINE_VAL_STRING,
  93                   int flags = 0);
  94
  95     /**
  96         Add a switch @a name with an optional long name @a lng (no long name if it
  97         is empty, which is default), description @a desc and flags @a flags to the
  98         command line description.
  99     */
 100     void AddSwitch(const wxString& name,
 101                    const wxString& lng = wxEmptyString,
 102                    const wxString& desc = wxEmptyString,
 103                    int flags = 0);
 104
 105     /**
 106         Returns @true if long options are enabled, otherwise @false.
 107
 108         @see EnableLongOptions()
 109     */
 110     bool AreLongOptionsEnabled() const;
 111
 112     /**
 113         Before Parse() can be called, the command line
 114         parser object must have the command line to parse and also the rules saying
 115         which switches, options and parameters are valid - this is called command line
 116         description in what follows.
 117         You have complete freedom of choice as to when specify the required information,
 118         the only restriction is that it must be done before calling
 119         Parse().
 120         To specify the command line to parse you may use either one of constructors
 121         accepting it (@c wxCmdLineParser(argc, argv) or @c wxCmdLineParser(const
 122         wxString) usually)
 123         or, if you use the default constructor, you can do it later by calling
 124         SetCmdLine().
 125         The same holds for command line description: it can be specified either in
 126         the @ref wxcmdlineparserctor() constructor (with or without
 127         the command line itself) or constructed later using either
 128         SetDesc() or combination of
 129         AddSwitch(),
 130         AddOption() and
 131         AddParam() methods.
 132         Using constructors or SetDesc() uses a (usually
 133         @c const static) table containing the command line description. If you want
 134         to decide which options to accept during the run-time, using one of the
 135         @c AddXXX() functions above might be preferable.
 136     */
 137
 138
 139     /**
 140         Breaks down the string containing the full command line in words. The words are
 141         separated by whitespace. The quotes can be used in the input string to quote
 142         the white space and the back slashes can be used to quote the quotes.
 143     */
 144     static wxArrayString ConvertStringToArgs(const wxChar cmdline);
 145
 146     /**
 147         wxCmdLineParser has several global options which may be changed by the
 148         application. All of the functions described in this section should be called
 149         before Parse().
 150         First global option is the support for long (also known as GNU-style) options.
 151         The long options are the ones which start with two dashes (@c "--") and look
 152         like this: @c --verbose, i.e. they generally are complete words and not some
 153         abbreviations of them. As long options are used by more and more applications,
 154         they are enabled by default, but may be disabled with
 155         DisableLongOptions().
 156         Another global option is the set of characters which may be used to start an
 157         option (otherwise, the word on the command line is assumed to be a parameter).
 158         Under Unix, @c '-' is always used, but Windows has at least two common
 159         choices for this: @c '-' and @c '/'. Some programs also use @c '+'.
 160         The default is to use what suits most the current platform, but may be changed
 161         with SetSwitchChars() method.
 162         Finally, SetLogo() can be used to show some
 163         application-specific text before the explanation given by
 164         Usage() function.
 165     */
 166
 167
 168     /**
 169         Identical to @ref enablelongoptions() EnableLongOptions(@false).
 170     */
 171     void DisableLongOptions();
 172
 173     /**
 174         Enable or disable support for the long options.
 175         As long options are not (yet) POSIX-compliant, this option allows to disable
 176         them.
 177
 178         @see Customization() and AreLongOptionsEnabled()
 179     */
 180     void EnableLongOptions(bool enable = true);
 181
 182     //@{
 183     /**
 184         Returns @true if an option taking a date value was found and stores the
 185         value in the provided pointer (which should not be @NULL).
 186     */
 187     bool Found(const wxString& name) const;
 188     bool Found(const wxString& name, wxString* value) const;
 189     bool Found(const wxString& name, long* value) const;
 190     bool Found(const wxString& name, double* value) const;
 191     bool Found(const wxString& name, wxDateTime* value) const;
 192     //@}
 193
 194     /**
 195         Returns the value of Nth parameter (as string only).
 196     */
 197     wxString GetParam(size_t n = 0u) const;
 198
 199     /**
 200         Returns the number of parameters found. This function makes sense mostly if you
 201         had used @c wxCMD_LINE_PARAM_MULTIPLE flag.
 202     */
 203     size_t GetParamCount() const;
 204
 205     /**
 206         After calling Parse() (and if it returned 0),
 207         you may access the results of parsing using one of overloaded @c Found()
 208         methods.
 209         For a simple switch, you will simply call
 210         Found() to determine if the switch was given
 211         or not, for an option or a parameter, you will call a version of @c Found()
 212         which also returns the associated value in the provided variable. All
 213         @c Found() functions return @true if the switch or option were found in the
 214         command line or @false if they were not specified.
 215     */
 216
 217
 218     /**
 219         Parse the command line, return 0 if ok, -1 if @c "-h" or @c "--help"
 220         option was encountered and the help message was given or a positive value if a
 221         syntax error occurred.
 222
 223         @param giveUsage
 224             If @true (default), the usage message is given if a
 225             syntax error was encountered while parsing the command line or if help was
 226             requested. If @false, only error messages about possible syntax errors
 227             are given, use Usage to show the usage message
 228             from the caller if needed.
 229     */
 230     int Parse(bool giveUsage = true);
 231
 232     /**
 233         After the command line description was constructed and the desired options were
 234         set, you can finally call Parse() method.
 235         It returns 0 if the command line was correct and was parsed, -1 if the help
 236         option was specified (this is a separate case as, normally, the program will
 237         terminate after this) or a positive number if there was an error during the
 238         command line parsing.
 239         In the latter case, the appropriate error message and usage information are
 240         logged by wxCmdLineParser itself using the standard wxWidgets logging functions.
 241     */
 242
 243
 244     //@{
 245     /**
 246         Set command line to parse after using one of the constructors which don't do it.
 247     */
 248     void SetCmdLine(int argc, char** argv);
 249     void SetCmdLine(int argc, wchar_t** argv);
 250     void SetCmdLine(const wxString& cmdline);
 251     //@}
 252
 253     /**
 254         Construct the command line description
 255         Take the command line description from the wxCMD_LINE_NONE terminated table.
 256         Example of usage:
 257     */
 258     void SetDesc(const wxCmdLineEntryDesc* desc);
 259
 260     /**
 261         @a logo is some extra text which will be shown by
 262         Usage() method.
 263     */
 264     void SetLogo(const wxString& logo);
 265
 266     /**
 267         @a switchChars contains all characters with which an option or switch may
 268         start. Default is @c "-" for Unix, @c "-/" for Windows.
 269     */
 270     void SetSwitchChars(const wxString& switchChars);
 271
 272     /**
 273         Give the standard usage message describing all program options. It will use the
 274         options and parameters descriptions specified earlier, so the resulting message
 275         will not be helpful to the user unless the descriptions were indeed specified.
 276
 277         @see SetLogo()
 278     */
 279     void Usage() const;
 280 };
 281