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     const bool Found(const wxString& name, wxString* value) const;
 189     const bool Found(const wxString& name, long* value) const;
 190     const bool Found(const wxString& name, wxDateTime* value) const;
 191     //@}
 192
 193     /**
 194         Returns the value of Nth parameter (as string only).
 195     */
 196     wxString GetParam(size_t n = 0u) const;
 197
 198     /**
 199         Returns the number of parameters found. This function makes sense mostly if you
 200         had used @c wxCMD_LINE_PARAM_MULTIPLE flag.
 201     */
 202     size_t GetParamCount() const;
 203
 204     /**
 205         After calling Parse() (and if it returned 0),
 206         you may access the results of parsing using one of overloaded @c Found()
 207         methods.
 208         For a simple switch, you will simply call
 209         Found() to determine if the switch was given
 210         or not, for an option or a parameter, you will call a version of @c Found()
 211         which also returns the associated value in the provided variable. All
 212         @c Found() functions return @true if the switch or option were found in the
 213         command line or @false if they were not specified.
 214     */
 215
 216
 217     /**
 218         Parse the command line, return 0 if ok, -1 if @c "-h" or @c "--help"
 219         option was encountered and the help message was given or a positive value if a
 220         syntax error occurred.
 221
 222         @param giveUsage
 223             If @true (default), the usage message is given if a
 224             syntax error was encountered while parsing the command line or if help was
 225             requested. If @false, only error messages about possible syntax errors
 226             are given, use Usage to show the usage message
 227             from the caller if needed.
 228     */
 229     int Parse(bool giveUsage = true);
 230
 231     /**
 232         After the command line description was constructed and the desired options were
 233         set, you can finally call Parse() method.
 234         It returns 0 if the command line was correct and was parsed, -1 if the help
 235         option was specified (this is a separate case as, normally, the program will
 236         terminate after this) or a positive number if there was an error during the
 237         command line parsing.
 238         In the latter case, the appropriate error message and usage information are
 239         logged by wxCmdLineParser itself using the standard wxWidgets logging functions.
 240     */
 241
 242
 243     //@{
 244     /**
 245         Set command line to parse after using one of the constructors which don't do it.
 246     */
 247     void SetCmdLine(int argc, char** argv);
 248     void SetCmdLine(int argc, wchar_t** argv);
 249     void SetCmdLine(const wxString& cmdline);
 250     //@}
 251
 252     /**
 253         Construct the command line description
 254         Take the command line description from the wxCMD_LINE_NONE terminated table.
 255         Example of usage:
 256     */
 257     void SetDesc(const wxCmdLineEntryDesc* desc);
 258
 259     /**
 260         @a logo is some extra text which will be shown by
 261         Usage() method.
 262     */
 263     void SetLogo(const wxString& logo);
 264
 265     /**
 266         @a switchChars contains all characters with which an option or switch may
 267         start. Default is @c "-" for Unix, @c "-/" for Windows.
 268     */
 269     void SetSwitchChars(const wxString& switchChars);
 270
 271     /**
 272         Give the standard usage message describing all program options. It will use the
 273         options and parameters descriptions specified earlier, so the resulting message
 274         will not be helpful to the user unless the descriptions were indeed specified.
 275
 276         @see SetLogo()
 277     */
 278     void Usage() const;
 279 };
 280