]> git.saurik.com Git - wxWidgets.git/blob - interface/cmdline.h
add const qualifiers
[wxWidgets.git] / interface / cmdline.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: cmdline.h
3 // Purpose: documentation for wxCmdLineParser class
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxCmdLineParser
11 @wxheader{cmdline.h}
12
13 wxCmdLineParser is a class for parsing the command line.
14
15 It has the following features:
16
17 distinguishes options, switches and parameters; allows option grouping
18 allows both short and long options
19 automatically generates the usage message from the command line description
20 does type checks on the options values (number, date, ...).
21
22 To use it you should follow these steps:
23
24 @ref wxCmdLineParser::construction construct an object of this class
25 giving it the command line to parse and optionally its description or use
26 @c AddXXX() functions later
27 call @c Parse()
28 use @c Found() to retrieve the results
29
30 In the documentation below the following terminology is used:
31
32
33
34 switch
35
36
37 This is a boolean option which can be given or not, but
38 which doesn't have any value. We use the word switch to distinguish such boolean
39 options from more generic options like those described below. For example,
40 @c -v might be a switch meaning "enable verbose mode".
41
42
43 option
44
45
46 Option for us here is something which comes with a value 0
47 unlike a switch. For example, @c -o:filename might be an option which allows
48 to specify the name of the output file.
49
50
51 parameter
52
53
54 This is a required program argument.
55
56
57
58 @library{wxbase}
59 @category{appmanagement}
60
61 @seealso
62 wxApp::argc and wxApp::argv, console sample
63 */
64 class wxCmdLineParser
65 {
66 public:
67 //@{
68 /**
69 Specifies both the command line (in Windows format) and the
70 @ref setdesc() "command line description".
71 */
72 wxCmdLineParser();
73 wxCmdLineParser(int argc, char** argv);
74 wxCmdLineParser(int argc, wchar_t** argv);
75 wxCmdLineParser(const wxString& cmdline);
76 wxCmdLineParser(const wxCmdLineEntryDesc* desc);
77 wxCmdLineParser(const wxCmdLineEntryDesc* desc, int argc,
78 char** argv);
79 wxCmdLineParser(const wxCmdLineEntryDesc* desc,
80 const wxString& cmdline);
81 //@}
82
83 /**
84 Frees resources allocated by the object.
85 @b NB: destructor is not virtual, don't use this class polymorphically.
86 */
87 ~wxCmdLineParser();
88
89 /**
90 Add an option @a name with an optional long name @a lng (no long name if
91 it is empty, which is default) taking a value of the given type (string by
92 default) to the command line description.
93 */
94 void AddOption(const wxString& name,
95 const wxString& lng = wxEmptyString,
96 const wxString& desc = wxEmptyString,
97 wxCmdLineParamType type = wxCMD_LINE_VAL_STRING,
98 int flags = 0);
99
100 /**
101 Add a parameter of the given @a type to the command line description.
102 */
103 void AddParam(const wxString& desc = wxEmptyString,
104 wxCmdLineParamType type = wxCMD_LINE_VAL_STRING,
105 int flags = 0);
106
107 /**
108 Add a switch @a name with an optional long name @a lng (no long name if it
109 is empty, which is default), description @a desc and flags @a flags to the
110 command line description.
111 */
112 void AddSwitch(const wxString& name,
113 const wxString& lng = wxEmptyString,
114 const wxString& desc = wxEmptyString,
115 int flags = 0);
116
117 /**
118 Returns @true if long options are enabled, otherwise @false.
119
120 @see EnableLongOptions()
121 */
122 bool AreLongOptionsEnabled();
123
124 /**
125 Before Parse() can be called, the command line
126 parser object must have the command line to parse and also the rules saying
127 which switches, options and parameters are valid - this is called command line
128 description in what follows.
129 You have complete freedom of choice as to when specify the required information,
130 the only restriction is that it must be done before calling
131 Parse().
132 To specify the command line to parse you may use either one of constructors
133 accepting it (@c wxCmdLineParser(argc, argv) or @c wxCmdLineParser(const
134 wxString) usually)
135 or, if you use the default constructor, you can do it later by calling
136 SetCmdLine().
137 The same holds for command line description: it can be specified either in
138 the @ref wxcmdlineparserctor() constructor (with or without
139 the command line itself) or constructed later using either
140 SetDesc() or combination of
141 AddSwitch(),
142 AddOption() and
143 AddParam() methods.
144 Using constructors or SetDesc() uses a (usually
145 @c const static) table containing the command line description. If you want
146 to decide which options to accept during the run-time, using one of the
147 @c AddXXX() functions above might be preferable.
148 */
149
150
151 /**
152 Breaks down the string containing the full command line in words. The words are
153 separated by whitespace. The quotes can be used in the input string to quote
154 the white space and the back slashes can be used to quote the quotes.
155 */
156 static wxArrayString ConvertStringToArgs(const wxChar cmdline);
157
158 /**
159 wxCmdLineParser has several global options which may be changed by the
160 application. All of the functions described in this section should be called
161 before Parse().
162 First global option is the support for long (also known as GNU-style) options.
163 The long options are the ones which start with two dashes (@c "--") and look
164 like this: @c --verbose, i.e. they generally are complete words and not some
165 abbreviations of them. As long options are used by more and more applications,
166 they are enabled by default, but may be disabled with
167 DisableLongOptions().
168 Another global option is the set of characters which may be used to start an
169 option (otherwise, the word on the command line is assumed to be a parameter).
170 Under Unix, @c '-' is always used, but Windows has at least two common
171 choices for this: @c '-' and @c '/'. Some programs also use @c '+'.
172 The default is to use what suits most the current platform, but may be changed
173 with SetSwitchChars() method.
174 Finally, SetLogo() can be used to show some
175 application-specific text before the explanation given by
176 Usage() function.
177 */
178
179
180 /**
181 Identical to @ref enablelongoptions() EnableLongOptions(@false).
182 */
183 void DisableLongOptions();
184
185 /**
186 Enable or disable support for the long options.
187 As long options are not (yet) POSIX-compliant, this option allows to disable
188 them.
189
190 @see Customization() and AreLongOptionsEnabled()
191 */
192 void EnableLongOptions(bool enable = true);
193
194 //@{
195 /**
196 Returns @true if an option taking a date value was found and stores the
197 value in the provided pointer (which should not be @NULL).
198 */
199 bool Found(const wxString& name) const;
200 const bool Found(const wxString& name, wxString* value) const;
201 const bool Found(const wxString& name, long* value) const;
202 const bool Found(const wxString& name, wxDateTime* value) const;
203 //@}
204
205 /**
206 Returns the value of Nth parameter (as string only).
207 */
208 wxString GetParam(size_t n = 0u) const;
209
210 /**
211 Returns the number of parameters found. This function makes sense mostly if you
212 had used @c wxCMD_LINE_PARAM_MULTIPLE flag.
213 */
214 size_t GetParamCount() const;
215
216 /**
217 After calling Parse() (and if it returned 0),
218 you may access the results of parsing using one of overloaded @c Found()
219 methods.
220 For a simple switch, you will simply call
221 Found() to determine if the switch was given
222 or not, for an option or a parameter, you will call a version of @c Found()
223 which also returns the associated value in the provided variable. All
224 @c Found() functions return @true if the switch or option were found in the
225 command line or @false if they were not specified.
226 */
227
228
229 /**
230 Parse the command line, return 0 if ok, -1 if @c "-h" or @c "--help"
231 option was encountered and the help message was given or a positive value if a
232 syntax error occurred.
233
234 @param giveUsage
235 If @true (default), the usage message is given if a
236 syntax error was encountered while parsing the command line or if help was
237 requested. If @false, only error messages about possible syntax errors
238 are given, use Usage to show the usage message
239 from the caller if needed.
240 */
241 int Parse(bool giveUsage = true);
242
243 /**
244 After the command line description was constructed and the desired options were
245 set, you can finally call Parse() method.
246 It returns 0 if the command line was correct and was parsed, -1 if the help
247 option was specified (this is a separate case as, normally, the program will
248 terminate after this) or a positive number if there was an error during the
249 command line parsing.
250 In the latter case, the appropriate error message and usage information are
251 logged by wxCmdLineParser itself using the standard wxWidgets logging functions.
252 */
253
254
255 //@{
256 /**
257 Set command line to parse after using one of the constructors which don't do it.
258 */
259 void SetCmdLine(int argc, char** argv);
260 void SetCmdLine(int argc, wchar_t** argv);
261 void SetCmdLine(const wxString& cmdline);
262 //@}
263
264 /**
265 Construct the command line description
266 Take the command line description from the wxCMD_LINE_NONE terminated table.
267 Example of usage:
268 */
269 void SetDesc(const wxCmdLineEntryDesc* desc);
270
271 /**
272 @a logo is some extra text which will be shown by
273 Usage() method.
274 */
275 void SetLogo(const wxString& logo);
276
277 /**
278 @a switchChars contains all characters with which an option or switch may
279 start. Default is @c "-" for Unix, @c "-/" for Windows.
280 */
281 void SetSwitchChars(const wxString& switchChars);
282
283 /**
284 Give the standard usage message describing all program options. It will use the
285 options and parameters descriptions specified earlier, so the resulting message
286 will not be helpful to the user unless the descriptions were indeed specified.
287
288 @see SetLogo()
289 */
290 void Usage();
291 };