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