include/wx/cmdline.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/cmdline.h
   3 // Purpose:     wxCmdLineParser and related classes for parsing the command
   4 //              line options
   5 // Author:      Vadim Zeitlin
   6 // Modified by:
   7 // Created:     04.01.00
   8 // RCS-ID:      $Id$
   9 // Copyright:   (c) 2000 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
  10 // Licence:     wxWindows licence
  11 ///////////////////////////////////////////////////////////////////////////////
  12
  13 #ifndef _WX_CMDLINE_H_
  14 #define _WX_CMDLINE_H_
  15
  16 #include "wx/defs.h"
  17
  18 #include "wx/string.h"
  19 #include "wx/arrstr.h"
  20 #include "wx/cmdargs.h"
  21
  22 // determines ConvertStringToArgs() behaviour
  23 enum wxCmdLineSplitType
  24 {
  25     wxCMD_LINE_SPLIT_DOS,
  26     wxCMD_LINE_SPLIT_UNIX
  27 };
  28
  29 #if wxUSE_CMDLINE_PARSER
  30
  31 class WXDLLIMPEXP_FWD_BASE wxDateTime;
  32
  33 // ----------------------------------------------------------------------------
  34 // constants
  35 // ----------------------------------------------------------------------------
  36
  37 // by default, options are optional (sic) and each call to AddParam() allows
  38 // one more parameter - this may be changed by giving non-default flags to it
  39 enum wxCmdLineEntryFlags
  40 {
  41     wxCMD_LINE_OPTION_MANDATORY = 0x01, // this option must be given
  42     wxCMD_LINE_PARAM_OPTIONAL   = 0x02, // the parameter may be omitted
  43     wxCMD_LINE_PARAM_MULTIPLE   = 0x04, // the parameter may be repeated
  44     wxCMD_LINE_OPTION_HELP      = 0x08, // this option is a help request
  45     wxCMD_LINE_NEEDS_SEPARATOR  = 0x10, // must have sep before the value
  46     wxCMD_LINE_SWITCH_NEGATABLE = 0x20  // this switch can be negated (e.g. /S-)
  47 };
  48
  49 // an option value or parameter may be a string (the most common case), a
  50 // number or a date
  51 enum wxCmdLineParamType
  52 {
  53     wxCMD_LINE_VAL_STRING,  // should be 0 (default)
  54     wxCMD_LINE_VAL_NUMBER,
  55     wxCMD_LINE_VAL_DATE,
  56     wxCMD_LINE_VAL_DOUBLE,
  57     wxCMD_LINE_VAL_NONE
  58 };
  59
  60 // for constructing the cmd line description using Init()
  61 enum wxCmdLineEntryType
  62 {
  63     wxCMD_LINE_SWITCH,
  64     wxCMD_LINE_OPTION,
  65     wxCMD_LINE_PARAM,
  66     wxCMD_LINE_USAGE_TEXT,
  67     wxCMD_LINE_NONE         // to terminate the list
  68 };
  69
  70 // Possible return values of wxCmdLineParser::FoundSwitch()
  71 enum wxCmdLineSwitchState
  72 {
  73     wxCMD_SWITCH_OFF = -1,  // Found but turned off/negated.
  74     wxCMD_SWITCH_NOT_FOUND, // Not found at all.
  75     wxCMD_SWITCH_ON         // Found in normal state.
  76 };
  77
  78 // ----------------------------------------------------------------------------
  79 // wxCmdLineEntryDesc is a description of one command line
  80 // switch/option/parameter
  81 // ----------------------------------------------------------------------------
  82
  83 struct wxCmdLineEntryDesc
  84 {
  85     wxCmdLineEntryType kind;
  86     const char *shortName;
  87     const char *longName;
  88     const char *description;
  89     wxCmdLineParamType type;
  90     int flags;
  91 };
  92
  93 // the list of wxCmdLineEntryDesc objects should be terminated with this one
  94 #define wxCMD_LINE_DESC_END \
  95         { wxCMD_LINE_NONE, NULL, NULL, NULL, wxCMD_LINE_VAL_NONE, 0x0 }
  96
  97 // ----------------------------------------------------------------------------
  98 // wxCmdLineParser is a class for parsing command line.
  99 //
 100 // It has the following features:
 101 //
 102 // 1. distinguishes options, switches and parameters; allows option grouping
 103 // 2. allows both short and long options
 104 // 3. automatically generates the usage message from the cmd line description
 105 // 4. does type checks on the options values (number, date, ...)
 106 //
 107 // To use it you should:
 108 //
 109 // 1. construct it giving it the cmd line to parse and optionally its desc
 110 // 2. construct the cmd line description using AddXXX() if not done in (1)
 111 // 3. call Parse()
 112 // 4. use GetXXX() to retrieve the parsed info
 113 // ----------------------------------------------------------------------------
 114
 115 class WXDLLIMPEXP_BASE wxCmdLineParser
 116 {
 117 public:
 118     // ctors and initializers
 119     // ----------------------
 120
 121     // default ctor or ctor giving the cmd line in either Unix or Win form
 122     wxCmdLineParser() { Init(); }
 123     wxCmdLineParser(int argc, char **argv) { Init(); SetCmdLine(argc, argv); }
 124 #if wxUSE_UNICODE
 125     wxCmdLineParser(int argc, wxChar **argv) { Init(); SetCmdLine(argc, argv); }
 126     wxCmdLineParser(int argc, const wxCmdLineArgsArray& argv)
 127         { Init(); SetCmdLine(argc, argv); }
 128 #endif // wxUSE_UNICODE
 129     wxCmdLineParser(const wxString& cmdline) { Init(); SetCmdLine(cmdline); }
 130
 131     // the same as above, but also gives the cmd line description - otherwise,
 132     // use AddXXX() later
 133     wxCmdLineParser(const wxCmdLineEntryDesc *desc)
 134         { Init(); SetDesc(desc); }
 135     wxCmdLineParser(const wxCmdLineEntryDesc *desc, int argc, char **argv)
 136         { Init(); SetCmdLine(argc, argv); SetDesc(desc); }
 137 #if wxUSE_UNICODE
 138     wxCmdLineParser(const wxCmdLineEntryDesc *desc, int argc, wxChar **argv)
 139         { Init(); SetCmdLine(argc, argv); SetDesc(desc); }
 140     wxCmdLineParser(const wxCmdLineEntryDesc *desc,
 141                     int argc,
 142                     const wxCmdLineArgsArray& argv)
 143         { Init(); SetCmdLine(argc, argv); SetDesc(desc); }
 144 #endif // wxUSE_UNICODE
 145     wxCmdLineParser(const wxCmdLineEntryDesc *desc, const wxString& cmdline)
 146         { Init(); SetCmdLine(cmdline); SetDesc(desc); }
 147
 148     // set cmd line to parse after using one of the ctors which don't do it
 149     void SetCmdLine(int argc, char **argv);
 150 #if wxUSE_UNICODE
 151     void SetCmdLine(int argc, wxChar **argv);
 152     void SetCmdLine(int argc, const wxCmdLineArgsArray& argv);
 153 #endif // wxUSE_UNICODE
 154     void SetCmdLine(const wxString& cmdline);
 155
 156     // not virtual, don't use this class polymorphically
 157     ~wxCmdLineParser();
 158
 159     // set different parser options
 160     // ----------------------------
 161
 162     // by default, '-' is switch char under Unix, '-' or '/' under Win:
 163     // switchChars contains all characters with which an option or switch may
 164     // start
 165     void SetSwitchChars(const wxString& switchChars);
 166
 167     // long options are not POSIX-compliant, this option allows to disable them
 168     void EnableLongOptions(bool enable = true);
 169     void DisableLongOptions() { EnableLongOptions(false); }
 170
 171     bool AreLongOptionsEnabled() const;
 172
 173     // extra text may be shown by Usage() method if set by this function
 174     void SetLogo(const wxString& logo);
 175
 176     // construct the cmd line description
 177     // ----------------------------------
 178
 179     // take the cmd line description from the wxCMD_LINE_NONE terminated table
 180     void SetDesc(const wxCmdLineEntryDesc *desc);
 181
 182     // a switch: i.e. an option without value
 183     void AddSwitch(const wxString& name, const wxString& lng = wxEmptyString,
 184                    const wxString& desc = wxEmptyString,
 185                    int flags = 0);
 186     void AddLongSwitch(const wxString& lng,
 187                        const wxString& desc = wxEmptyString,
 188                        int flags = 0)
 189     {
 190         AddSwitch(wxString(), lng, desc, flags);
 191     }
 192
 193     // an option taking a value of the given type
 194     void AddOption(const wxString& name, const wxString& lng = wxEmptyString,
 195                    const wxString& desc = wxEmptyString,
 196                    wxCmdLineParamType type = wxCMD_LINE_VAL_STRING,
 197                    int flags = 0);
 198     void AddLongOption(const wxString& lng,
 199                        const wxString& desc = wxEmptyString,
 200                        wxCmdLineParamType type = wxCMD_LINE_VAL_STRING,
 201                        int flags = 0)
 202     {
 203         AddOption(wxString(), lng, desc, type, flags);
 204     }
 205
 206     // a parameter
 207     void AddParam(const wxString& desc = wxEmptyString,
 208                   wxCmdLineParamType type = wxCMD_LINE_VAL_STRING,
 209                   int flags = 0);
 210
 211     // add an explanatory text to be shown to the user in help
 212     void AddUsageText(const wxString& text);
 213
 214     // actions
 215     // -------
 216
 217     // parse the command line, return 0 if ok, -1 if "-h" or "--help" option
 218     // was encountered and the help message was given or a positive value if a
 219     // syntax error occurred
 220     //
 221     // if showUsage is true, Usage() is called in case of syntax error or if
 222     // help was requested
 223     int Parse(bool showUsage = true);
 224
 225     // give the usage message describing all program options
 226     void Usage() const;
 227
 228     // return the usage string, call Usage() to directly show it to the user
 229     wxString GetUsageString() const;
 230
 231     // get the command line arguments
 232     // ------------------------------
 233
 234     // returns true if the given switch was found
 235     bool Found(const wxString& name) const;
 236
 237     // Returns wxCMD_SWITCH_NOT_FOUND if the switch was not found at all,
 238     // wxCMD_SWITCH_ON if it was found in normal state and wxCMD_SWITCH_OFF if
 239     // it was found but negated (i.e. followed by "-", this can only happen for
 240     // the switches with wxCMD_LINE_SWITCH_NEGATABLE flag).
 241     wxCmdLineSwitchState FoundSwitch(const wxString& name) const;
 242
 243     // returns true if an option taking a string value was found and stores the
 244     // value in the provided pointer
 245     bool Found(const wxString& name, wxString *value) const;
 246
 247     // returns true if an option taking an integer value was found and stores
 248     // the value in the provided pointer
 249     bool Found(const wxString& name, long *value) const;
 250
 251     // returns true if an option taking a double value was found and stores
 252     // the value in the provided pointer
 253     bool Found(const wxString& name, double *value) const;
 254
 255 #if wxUSE_DATETIME
 256     // returns true if an option taking a date value was found and stores the
 257     // value in the provided pointer
 258     bool Found(const wxString& name, wxDateTime *value) const;
 259 #endif // wxUSE_DATETIME
 260
 261     // gets the number of parameters found
 262     size_t GetParamCount() const;
 263
 264     // gets the value of Nth parameter (as string only for now)
 265     wxString GetParam(size_t n = 0u) const;
 266
 267     // Resets switches and options
 268     void Reset();
 269
 270     // break down the command line in arguments
 271     static wxArrayString
 272     ConvertStringToArgs(const wxString& cmdline,
 273                         wxCmdLineSplitType type = wxCMD_LINE_SPLIT_DOS);
 274
 275 private:
 276     // common part of all ctors
 277     void Init();
 278
 279     struct wxCmdLineParserData *m_data;
 280
 281     wxDECLARE_NO_COPY_CLASS(wxCmdLineParser);
 282 };
 283
 284 #else // !wxUSE_CMDLINE_PARSER
 285
 286 // this function is always available (even if !wxUSE_CMDLINE_PARSER) because it
 287 // is used by wxWin itself under Windows
 288 class WXDLLIMPEXP_BASE wxCmdLineParser
 289 {
 290 public:
 291     static wxArrayString
 292     ConvertStringToArgs(const wxString& cmdline,
 293                         wxCmdLineSplitType type = wxCMD_LINE_SPLIT_DOS);
 294 };
 295
 296 #endif // wxUSE_CMDLINE_PARSER/!wxUSE_CMDLINE_PARSER
 297
 298 #endif // _WX_CMDLINE_H_