1 ///////////////////////////////////////////////////////////////////////////////
3 // Purpose: wxCmdLineParser and related classes for parsing the command
5 // Author: Vadim Zeitlin
9 // Copyright: (c) 2000 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
10 // Licence: wxWindows licence
11 ///////////////////////////////////////////////////////////////////////////////
13 #ifndef _WX_CMDLINE_H_
14 #define _WX_CMDLINE_H_
18 #include "wx/string.h"
19 #include "wx/arrstr.h"
20 #include "wx/cmdargs.h"
22 #if wxUSE_CMDLINE_PARSER
24 class WXDLLIMPEXP_FWD_BASE wxDateTime
;
26 // ----------------------------------------------------------------------------
28 // ----------------------------------------------------------------------------
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
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
41 // an option value or parameter may be a string (the most common case), a
43 enum wxCmdLineParamType
45 wxCMD_LINE_VAL_STRING
, // should be 0 (default)
46 wxCMD_LINE_VAL_NUMBER
,
51 // for constructing the cmd line description using Init()
52 enum wxCmdLineEntryType
57 wxCMD_LINE_NONE
// to terminate the list
60 // ----------------------------------------------------------------------------
61 // wxCmdLineEntryDesc is a description of one command line
62 // switch/option/parameter
63 // ----------------------------------------------------------------------------
65 struct wxCmdLineEntryDesc
67 wxCmdLineEntryType kind
;
68 const char *shortName
;
70 const char *description
;
71 wxCmdLineParamType type
;
75 // the list of wxCmdLineEntryDesc objects should be terminated with this one
76 #define wxCMD_LINE_DESC_END \
77 { wxCMD_LINE_NONE, NULL, NULL, NULL, wxCMD_LINE_VAL_NONE, 0x0 }
79 // ----------------------------------------------------------------------------
80 // wxCmdLineParser is a class for parsing command line.
82 // It has the following features:
84 // 1. distinguishes options, switches and parameters; allows option grouping
85 // 2. allows both short and long options
86 // 3. automatically generates the usage message from the cmd line description
87 // 4. does type checks on the options values (number, date, ...)
89 // To use it you should:
91 // 1. construct it giving it the cmd line to parse and optionally its desc
92 // 2. construct the cmd line description using AddXXX() if not done in (1)
94 // 4. use GetXXX() to retrieve the parsed info
95 // ----------------------------------------------------------------------------
97 class WXDLLIMPEXP_BASE wxCmdLineParser
100 // ctors and initializers
101 // ----------------------
103 // default ctor or ctor giving the cmd line in either Unix or Win form
104 wxCmdLineParser() { Init(); }
105 wxCmdLineParser(int argc
, char **argv
) { Init(); SetCmdLine(argc
, argv
); }
107 wxCmdLineParser(int argc
, wxChar
**argv
) { Init(); SetCmdLine(argc
, argv
); }
108 wxCmdLineParser(int argc
, const wxCmdLineArgsArray
& argv
)
109 { Init(); SetCmdLine(argc
, argv
); }
110 #endif // wxUSE_UNICODE
111 wxCmdLineParser(const wxString
& cmdline
) { Init(); SetCmdLine(cmdline
); }
113 // the same as above, but also gives the cmd line description - otherwise,
114 // use AddXXX() later
115 wxCmdLineParser(const wxCmdLineEntryDesc
*desc
)
116 { Init(); SetDesc(desc
); }
117 wxCmdLineParser(const wxCmdLineEntryDesc
*desc
, int argc
, char **argv
)
118 { Init(); SetCmdLine(argc
, argv
); SetDesc(desc
); }
120 wxCmdLineParser(const wxCmdLineEntryDesc
*desc
, int argc
, wxChar
**argv
)
121 { Init(); SetCmdLine(argc
, argv
); SetDesc(desc
); }
122 wxCmdLineParser(const wxCmdLineEntryDesc
*desc
,
124 const wxCmdLineArgsArray
& argv
)
125 { Init(); SetCmdLine(argc
, argv
); SetDesc(desc
); }
126 #endif // wxUSE_UNICODE
127 wxCmdLineParser(const wxCmdLineEntryDesc
*desc
, const wxString
& cmdline
)
128 { Init(); SetCmdLine(cmdline
); SetDesc(desc
); }
130 // set cmd line to parse after using one of the ctors which don't do it
131 void SetCmdLine(int argc
, char **argv
);
133 void SetCmdLine(int argc
, wxChar
**argv
);
134 void SetCmdLine(int argc
, const wxCmdLineArgsArray
& argv
);
135 #endif // wxUSE_UNICODE
136 void SetCmdLine(const wxString
& cmdline
);
138 // not virtual, don't use this class polymorphically
141 // set different parser options
142 // ----------------------------
144 // by default, '-' is switch char under Unix, '-' or '/' under Win:
145 // switchChars contains all characters with which an option or switch may
147 void SetSwitchChars(const wxString
& switchChars
);
149 // long options are not POSIX-compliant, this option allows to disable them
150 void EnableLongOptions(bool enable
= true);
151 void DisableLongOptions() { EnableLongOptions(false); }
153 bool AreLongOptionsEnabled() const;
155 // extra text may be shown by Usage() method if set by this function
156 void SetLogo(const wxString
& logo
);
158 // construct the cmd line description
159 // ----------------------------------
161 // take the cmd line description from the wxCMD_LINE_NONE terminated table
162 void SetDesc(const wxCmdLineEntryDesc
*desc
);
164 // a switch: i.e. an option without value
165 void AddSwitch(const wxString
& name
, const wxString
& lng
= wxEmptyString
,
166 const wxString
& desc
= wxEmptyString
,
169 // an option taking a value of the given type
170 void AddOption(const wxString
& name
, const wxString
& lng
= wxEmptyString
,
171 const wxString
& desc
= wxEmptyString
,
172 wxCmdLineParamType type
= wxCMD_LINE_VAL_STRING
,
176 void AddParam(const wxString
& desc
= wxEmptyString
,
177 wxCmdLineParamType type
= wxCMD_LINE_VAL_STRING
,
183 // parse the command line, return 0 if ok, -1 if "-h" or "--help" option
184 // was encountered and the help message was given or a positive value if a
185 // syntax error occurred
187 // if showUsage is true, Usage() is called in case of syntax error or if
188 // help was requested
189 int Parse(bool showUsage
= true);
191 // give the usage message describing all program options
194 // get the command line arguments
195 // ------------------------------
197 // returns true if the given switch was found
198 bool Found(const wxString
& name
) const;
200 // returns true if an option taking a string value was found and stores the
201 // value in the provided pointer
202 bool Found(const wxString
& name
, wxString
*value
) const;
204 // returns true if an option taking an integer value was found and stores
205 // the value in the provided pointer
206 bool Found(const wxString
& name
, long *value
) const;
209 // returns true if an option taking a date value was found and stores the
210 // value in the provided pointer
211 bool Found(const wxString
& name
, wxDateTime
*value
) const;
212 #endif // wxUSE_DATETIME
214 // gets the number of parameters found
215 size_t GetParamCount() const;
217 // gets the value of Nth parameter (as string only for now)
218 wxString
GetParam(size_t n
= 0u) const;
220 // Resets switches and options
223 // break down the command line in arguments
224 static wxArrayString
ConvertStringToArgs(const wxString
& cmdline
);
228 wxString
GetUsageString() const;
230 // common part of all ctors
233 struct wxCmdLineParserData
*m_data
;
235 DECLARE_NO_COPY_CLASS(wxCmdLineParser
)
238 #else // !wxUSE_CMDLINE_PARSER
240 // this function is always available (even if !wxUSE_CMDLINE_PARSER) because it
241 // is used by wxWin itself under Windows
242 class WXDLLIMPEXP_BASE wxCmdLineParser
245 static wxArrayString
ConvertStringToArgs(const wxString
& cmdline
);
248 #endif // wxUSE_CMDLINE_PARSER/!wxUSE_CMDLINE_PARSER
250 #endif // _WX_CMDLINE_H_