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