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