]>
git.saurik.com Git - wxWidgets.git/blob - interface/cmdline.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxCmdLineParser
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 @class wxCmdLineParser
13 wxCmdLineParser is a class for parsing the command line.
15 It has the following features:
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, ...).
22 To use it you should follow these steps:
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
28 use @c Found() to retrieve the results
30 In the documentation below the following terminology is used:
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".
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.
54 This is a required program argument.
59 @category{appmanagement}
61 @see wxApp::argc and wxApp::argv, console sample
68 Specifies both the command line (in Windows format) and the
69 @ref setdesc() "command line description".
72 wxCmdLineParser(int argc
, char** argv
);
73 wxCmdLineParser(int argc
, wchar_t** argv
);
74 wxCmdLineParser(const wxString
& cmdline
);
75 wxCmdLineParser(const wxCmdLineEntryDesc
* desc
);
76 wxCmdLineParser(const wxCmdLineEntryDesc
* desc
, int argc
,
78 wxCmdLineParser(const wxCmdLineEntryDesc
* desc
,
79 const wxString
& cmdline
);
83 Frees resources allocated by the object.
84 @b NB: destructor is not virtual, don't use this class polymorphically.
89 Add an option @a name with an optional long name @a lng (no long name if
90 it is empty, which is default) taking a value of the given type (string by
91 default) to the command line description.
93 void AddOption(const wxString
& name
,
94 const wxString
& lng
= wxEmptyString
,
95 const wxString
& desc
= wxEmptyString
,
96 wxCmdLineParamType type
= wxCMD_LINE_VAL_STRING
,
100 Add a parameter of the given @a type to the command line description.
102 void AddParam(const wxString
& desc
= wxEmptyString
,
103 wxCmdLineParamType type
= wxCMD_LINE_VAL_STRING
,
107 Add a switch @a name with an optional long name @a lng (no long name if it
108 is empty, which is default), description @a desc and flags @a flags to the
109 command line description.
111 void AddSwitch(const wxString
& name
,
112 const wxString
& lng
= wxEmptyString
,
113 const wxString
& desc
= wxEmptyString
,
117 Returns @true if long options are enabled, otherwise @false.
119 @see EnableLongOptions()
121 bool AreLongOptionsEnabled();
124 Before Parse() can be called, the command line
125 parser object must have the command line to parse and also the rules saying
126 which switches, options and parameters are valid - this is called command line
127 description in what follows.
128 You have complete freedom of choice as to when specify the required information,
129 the only restriction is that it must be done before calling
131 To specify the command line to parse you may use either one of constructors
132 accepting it (@c wxCmdLineParser(argc, argv) or @c wxCmdLineParser(const
134 or, if you use the default constructor, you can do it later by calling
136 The same holds for command line description: it can be specified either in
137 the @ref wxcmdlineparserctor() constructor (with or without
138 the command line itself) or constructed later using either
139 SetDesc() or combination of
143 Using constructors or SetDesc() uses a (usually
144 @c const static) table containing the command line description. If you want
145 to decide which options to accept during the run-time, using one of the
146 @c AddXXX() functions above might be preferable.
151 Breaks down the string containing the full command line in words. The words are
152 separated by whitespace. The quotes can be used in the input string to quote
153 the white space and the back slashes can be used to quote the quotes.
155 static wxArrayString
ConvertStringToArgs(const wxChar cmdline
);
158 wxCmdLineParser has several global options which may be changed by the
159 application. All of the functions described in this section should be called
161 First global option is the support for long (also known as GNU-style) options.
162 The long options are the ones which start with two dashes (@c "--") and look
163 like this: @c --verbose, i.e. they generally are complete words and not some
164 abbreviations of them. As long options are used by more and more applications,
165 they are enabled by default, but may be disabled with
166 DisableLongOptions().
167 Another global option is the set of characters which may be used to start an
168 option (otherwise, the word on the command line is assumed to be a parameter).
169 Under Unix, @c '-' is always used, but Windows has at least two common
170 choices for this: @c '-' and @c '/'. Some programs also use @c '+'.
171 The default is to use what suits most the current platform, but may be changed
172 with SetSwitchChars() method.
173 Finally, SetLogo() can be used to show some
174 application-specific text before the explanation given by
180 Identical to @ref enablelongoptions() EnableLongOptions(@false).
182 void DisableLongOptions();
185 Enable or disable support for the long options.
186 As long options are not (yet) POSIX-compliant, this option allows to disable
189 @see Customization() and AreLongOptionsEnabled()
191 void EnableLongOptions(bool enable
= true);
195 Returns @true if an option taking a date value was found and stores the
196 value in the provided pointer (which should not be @NULL).
198 bool Found(const wxString
& name
) const;
199 const bool Found(const wxString
& name
, wxString
* value
) const;
200 const bool Found(const wxString
& name
, long* value
) const;
201 const bool Found(const wxString
& name
, wxDateTime
* value
) const;
205 Returns the value of Nth parameter (as string only).
207 wxString
GetParam(size_t n
= 0u) const;
210 Returns the number of parameters found. This function makes sense mostly if you
211 had used @c wxCMD_LINE_PARAM_MULTIPLE flag.
213 size_t GetParamCount() const;
216 After calling Parse() (and if it returned 0),
217 you may access the results of parsing using one of overloaded @c Found()
219 For a simple switch, you will simply call
220 Found() to determine if the switch was given
221 or not, for an option or a parameter, you will call a version of @c Found()
222 which also returns the associated value in the provided variable. All
223 @c Found() functions return @true if the switch or option were found in the
224 command line or @false if they were not specified.
229 Parse the command line, return 0 if ok, -1 if @c "-h" or @c "--help"
230 option was encountered and the help message was given or a positive value if a
231 syntax error occurred.
234 If @true (default), the usage message is given if a
235 syntax error was encountered while parsing the command line or if help was
236 requested. If @false, only error messages about possible syntax errors
237 are given, use Usage to show the usage message
238 from the caller if needed.
240 int Parse(bool giveUsage
= true);
243 After the command line description was constructed and the desired options were
244 set, you can finally call Parse() method.
245 It returns 0 if the command line was correct and was parsed, -1 if the help
246 option was specified (this is a separate case as, normally, the program will
247 terminate after this) or a positive number if there was an error during the
248 command line parsing.
249 In the latter case, the appropriate error message and usage information are
250 logged by wxCmdLineParser itself using the standard wxWidgets logging functions.
256 Set command line to parse after using one of the constructors which don't do it.
258 void SetCmdLine(int argc
, char** argv
);
259 void SetCmdLine(int argc
, wchar_t** argv
);
260 void SetCmdLine(const wxString
& cmdline
);
264 Construct the command line description
265 Take the command line description from the wxCMD_LINE_NONE terminated table.
268 void SetDesc(const wxCmdLineEntryDesc
* desc
);
271 @a logo is some extra text which will be shown by
274 void SetLogo(const wxString
& logo
);
277 @a switchChars contains all characters with which an option or switch may
278 start. Default is @c "-" for Unix, @c "-/" for Windows.
280 void SetSwitchChars(const wxString
& switchChars
);
283 Give the standard usage message describing all program options. It will use the
284 options and parameters descriptions specified earlier, so the resulting message
285 will not be helpful to the user unless the descriptions were indeed specified.