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