]> git.saurik.com Git - wxWidgets.git/blame - include/wx/cmdline.h
Use kCGBlendModeExclusion for wxCOMPOSITION_XOR operation.
[wxWidgets.git] / include / wx / cmdline.h
CommitLineData
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
23enum wxCmdLineSplitType
24{
25 wxCMD_LINE_SPLIT_DOS,
26 wxCMD_LINE_SPLIT_UNIX
27};
28
ee0f5531
WS
29#if wxUSE_CMDLINE_PARSER
30
b5dbe15d 31class 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 39enum 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
51enum 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()
61enum 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()
71enum 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
83struct 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 115class WXDLLIMPEXP_BASE wxCmdLineParser
9f83044f
VZ
116{
117public:
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
275private:
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 288class WXDLLIMPEXP_BASE wxCmdLineParser
31f6de22
VZ
289{
290public:
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_