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