interface/cmdline.h

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