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