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