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