]>
Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: cmdline.h | |
e54c96f1 | 3 | // Purpose: interface of wxCmdLineParser |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | @class wxCmdLineParser | |
11 | @wxheader{cmdline.h} | |
7c913512 | 12 | |
23324ae1 | 13 | wxCmdLineParser is a class for parsing the command line. |
7c913512 | 14 | |
23324ae1 | 15 | It has the following features: |
7c913512 | 16 | |
779288b4 VZ |
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, ...). | |
7c913512 | 22 | |
23324ae1 | 23 | To use it you should follow these steps: |
7c913512 | 24 | |
779288b4 | 25 | -# @ref wxCmdLineParser::construction construct an object of this class |
7c913512 | 26 | giving it the command line to parse and optionally its description or use |
23324ae1 | 27 | @c AddXXX() functions later |
779288b4 VZ |
28 | -# call @c Parse() |
29 | -# use @c Found() to retrieve the results | |
7c913512 | 30 | |
23324ae1 | 31 | In the documentation below the following terminology is used: |
7c913512 | 32 | |
779288b4 | 33 | - @e switch |
23324ae1 FM |
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 | |
7c913512 | 36 | options from more generic options like those described below. For example, |
23324ae1 | 37 | @c -v might be a switch meaning "enable verbose mode". |
779288b4 | 38 | - @e option |
23324ae1 FM |
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. | |
779288b4 | 42 | - @e parameter |
23324ae1 | 43 | This is a required program argument. |
7c913512 FM |
44 | |
45 | ||
46 | ||
23324ae1 FM |
47 | @library{wxbase} |
48 | @category{appmanagement} | |
7c913512 | 49 | |
e54c96f1 | 50 | @see wxApp::argc and wxApp::argv, console sample |
23324ae1 | 51 | */ |
7c913512 | 52 | class wxCmdLineParser |
23324ae1 FM |
53 | { |
54 | public: | |
55 | //@{ | |
56 | /** | |
7c913512 | 57 | Specifies both the command line (in Windows format) and the |
23324ae1 FM |
58 | @ref setdesc() "command line description". |
59 | */ | |
60 | wxCmdLineParser(); | |
7c913512 FM |
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); | |
23324ae1 FM |
69 | //@} |
70 | ||
71 | /** | |
72 | Frees resources allocated by the object. | |
23324ae1 FM |
73 | @b NB: destructor is not virtual, don't use this class polymorphically. |
74 | */ | |
75 | ~wxCmdLineParser(); | |
76 | ||
77 | /** | |
4cc4bfaf | 78 | Add an option @a name with an optional long name @a lng (no long name if |
23324ae1 FM |
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 | /** | |
4cc4bfaf | 89 | Add a parameter of the given @a type to the command line description. |
23324ae1 FM |
90 | */ |
91 | void AddParam(const wxString& desc = wxEmptyString, | |
92 | wxCmdLineParamType type = wxCMD_LINE_VAL_STRING, | |
93 | int flags = 0); | |
94 | ||
95 | /** | |
4cc4bfaf FM |
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 | |
23324ae1 FM |
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. | |
3c4f71cc | 107 | |
4cc4bfaf | 108 | @see EnableLongOptions() |
23324ae1 | 109 | */ |
779288b4 | 110 | bool AreLongOptionsEnabled() const; |
23324ae1 FM |
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. | |
23324ae1 | 117 | You have complete freedom of choice as to when specify the required information, |
7c913512 | 118 | the only restriction is that it must be done before calling |
23324ae1 | 119 | Parse(). |
23324ae1 FM |
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) | |
7c913512 | 123 | or, if you use the default constructor, you can do it later by calling |
23324ae1 | 124 | SetCmdLine(). |
23324ae1 FM |
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 | |
7c913512 FM |
128 | SetDesc() or combination of |
129 | AddSwitch(), | |
130 | AddOption() and | |
23324ae1 | 131 | AddParam() methods. |
7c913512 | 132 | Using constructors or SetDesc() uses a (usually |
23324ae1 | 133 | @c const static) table containing the command line description. If you want |
7c913512 | 134 | to decide which options to accept during the run-time, using one of the |
23324ae1 FM |
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(). | |
23324ae1 FM |
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, | |
7c913512 | 154 | they are enabled by default, but may be disabled with |
23324ae1 | 155 | DisableLongOptions(). |
23324ae1 FM |
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. | |
23324ae1 | 162 | Finally, SetLogo() can be used to show some |
7c913512 | 163 | application-specific text before the explanation given by |
23324ae1 FM |
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. | |
23324ae1 FM |
175 | As long options are not (yet) POSIX-compliant, this option allows to disable |
176 | them. | |
3c4f71cc | 177 | |
4cc4bfaf | 178 | @see Customization() and AreLongOptionsEnabled() |
23324ae1 | 179 | */ |
4cc4bfaf | 180 | void EnableLongOptions(bool enable = true); |
23324ae1 FM |
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 | */ | |
328f5751 | 187 | bool Found(const wxString& name) const; |
b1859b1a VZ |
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; | |
23324ae1 FM |
192 | //@} |
193 | ||
194 | /** | |
195 | Returns the value of Nth parameter (as string only). | |
196 | */ | |
328f5751 | 197 | wxString GetParam(size_t n = 0u) const; |
23324ae1 FM |
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 | */ | |
328f5751 | 203 | size_t GetParamCount() const; |
23324ae1 FM |
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. | |
7c913512 | 209 | For a simple switch, you will simply call |
23324ae1 | 210 | Found() to determine if the switch was given |
7c913512 FM |
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 | |
23324ae1 FM |
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 | /** | |
7c913512 | 219 | Parse the command line, return 0 if ok, -1 if @c "-h" or @c "--help" |
23324ae1 FM |
220 | option was encountered and the help message was given or a positive value if a |
221 | syntax error occurred. | |
3c4f71cc | 222 | |
7c913512 | 223 | @param giveUsage |
4cc4bfaf FM |
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. | |
23324ae1 | 229 | */ |
4cc4bfaf | 230 | int Parse(bool giveUsage = true); |
23324ae1 FM |
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. | |
23324ae1 FM |
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); | |
7c913512 FM |
249 | void SetCmdLine(int argc, wchar_t** argv); |
250 | void SetCmdLine(const wxString& cmdline); | |
23324ae1 FM |
251 | //@} |
252 | ||
253 | /** | |
254 | Construct the command line description | |
23324ae1 | 255 | Take the command line description from the wxCMD_LINE_NONE terminated table. |
23324ae1 FM |
256 | Example of usage: |
257 | */ | |
258 | void SetDesc(const wxCmdLineEntryDesc* desc); | |
259 | ||
260 | /** | |
4cc4bfaf | 261 | @a logo is some extra text which will be shown by |
23324ae1 FM |
262 | Usage() method. |
263 | */ | |
264 | void SetLogo(const wxString& logo); | |
265 | ||
266 | /** | |
4cc4bfaf | 267 | @a switchChars contains all characters with which an option or switch may |
23324ae1 FM |
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. | |
3c4f71cc | 276 | |
4cc4bfaf | 277 | @see SetLogo() |
23324ae1 | 278 | */ |
779288b4 | 279 | void Usage() const; |
23324ae1 | 280 | }; |
e54c96f1 | 281 |