]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/latex/wx/cmdlpars.tex
Fixed to work with the new wxMacControl system.
[wxWidgets.git] / docs / latex / wx / cmdlpars.tex
... / ...
CommitLineData
1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2%% Name: cmdlpars.tex
3%% Purpose: wxCmdLineParser documentation
4%% Author: Vadim Zeitlin
5%% Modified by:
6%% Created: 27.03.00
7%% RCS-ID: $Id$
8%% Copyright: (c) Vadim Zeitlin
9%% License: wxWidgets license
10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11
12\section{\class{wxCmdLineParser}}\label{wxcmdlineparser}
13
14wxCmdLineParser is a class for parsing command line.
15
16It has the following features:
17
18\begin{enumerate}\itemsep=0pt
19\item distinguishes options, switches and parameters; allows option grouping
20\item allows both short and long options
21\item automatically generates the usage message from the command line description
22\item does type checks on the options values (number, date, $\ldots$).
23\end{enumerate}
24
25To use it you should follow these steps:
26
27\begin{enumerate}\itemsep=0pt
28\item \helpref{construct}{wxcmdlineparserconstruction} an object of this class
29giving it the command line to parse and optionally its description or use
30{\tt AddXXX()} functions later
31\item call {\tt Parse()}
32\item use {\tt Found()} to retrieve the results
33\end{enumerate}
34
35In the documentation below the following terminology is used:
36
37\begin{twocollist}\itemsep=0pt
38\twocolitem{switch}{This is a boolean option which can be given or not, but
39which doesn't have any value. We use the word switch to distinguish such boolean
40options from more generic options like those described below. For example,
41{\tt -v} might be a switch meaning "enable verbose mode".}
42\twocolitem{option}{Option for us here is something which comes with a value 0
43unlike a switch. For example, {\tt -o:filename} might be an option which allows
44to specify the name of the output file.}
45\twocolitem{parameter}{This is a required program argument.}
46\end{twocollist}
47
48\wxheading{Derived from}
49
50No base class
51
52\wxheading{Include files}
53
54<wx/cmdline.h>
55
56\wxheading{Constants}
57
58The structure wxCmdLineEntryDesc is used to describe the one command
59line switch, option or parameter. An array of such structures should be passed
60to \helpref{SetDesc()}{wxcmdlineparsersetdesc}. Also, the meanings of parameters
61of the {\tt AddXXX()} functions are the same as of the corresponding fields in
62this structure:
63
64\begin{verbatim}
65struct wxCmdLineEntryDesc
66{
67 wxCmdLineEntryType kind;
68 const wxChar *shortName;
69 const wxChar *longName;
70 const wxChar *description;
71 wxCmdLineParamType type;
72 int flags;
73};
74\end{verbatim}
75
76The type of a command line entity is in the {\tt kind} field and may be one of
77the following constants:
78
79{\small%
80\begin{verbatim}
81enum wxCmdLineEntryType
82{
83 wxCMD_LINE_SWITCH,
84 wxCMD_LINE_OPTION,
85 wxCMD_LINE_PARAM,
86 wxCMD_LINE_NONE // use this to terminate the list
87}
88\end{verbatim}
89}
90
91The field {\tt shortName} is the usual, short, name of the switch or the option.
92{\tt longName} is the corresponding long name or NULL if the option has no long
93name. Both of these fields are unused for the parameters. Both the short and
94long option names can contain only letters, digits and the underscores.
95
96{\tt description} is used by the \helpref{Usage()}{wxcmdlineparserusage} method
97to construct a help message explaining the syntax of the program.
98
99The possible values of {\tt type} which specifies the type of the value accepted
100by an option or parameter are:
101
102{\small%
103\begin{verbatim}
104enum wxCmdLineParamType
105{
106 wxCMD_LINE_VAL_STRING, // default
107 wxCMD_LINE_VAL_NUMBER,
108 wxCMD_LINE_VAL_DATE,
109 wxCMD_LINE_VAL_NONE
110}
111\end{verbatim}
112}
113
114Finally, the {\tt flags} field is a combination of the following bit masks:
115
116{\small%
117\begin{verbatim}
118enum
119{
120 wxCMD_LINE_OPTION_MANDATORY = 0x01, // this option must be given
121 wxCMD_LINE_PARAM_OPTIONAL = 0x02, // the parameter may be omitted
122 wxCMD_LINE_PARAM_MULTIPLE = 0x04, // the parameter may be repeated
123 wxCMD_LINE_OPTION_HELP = 0x08, // this option is a help request
124 wxCMD_LINE_NEEDS_SEPARATOR = 0x10, // must have sep before the value
125}
126\end{verbatim}
127}
128
129Notice that by default (i.e. if flags are just $0$), options are optional (sic)
130and each call to \helpref{AddParam()}{wxcmdlineparseraddparam} allows one more
131parameter - this may be changed by giving non-default flags to it, i.e. use
132{\tt wxCMD\_LINE\_OPTION\_MANDATORY} to require that the option is given and
133{\tt wxCMD\_LINE\_PARAM\_OPTIONAL} to make a parameter optional. Also,
134{\tt wxCMD\_LINE\_PARAM\_MULTIPLE} may be specified if the programs accepts a
135variable number of parameters - but it only can be given for the last parameter
136in the command line description. If you use this flag, you will probably need to
137use \helpref{GetParamCount}{wxcmdlineparsergetparamcount} to retrieve the number
138of parameters effectively specified after calling
139\helpref{Parse}{wxcmdlineparserparse}.
140
141The last flag {\tt wxCMD\_LINE\_NEEDS\_SEPARATOR} can be specified to require a
142separator (either a colon, an equal sign or white space) between the option
143name and its value. By default, no separator is required.
144
145\wxheading{See also}
146
147\helpref{wxApp::argc}{wxappargc} and \helpref{wxApp::argv}{wxappargv}\\
148console sample
149
150%%%%%%%%%%%%% Methods by group %%%%%%%%%%%%%
151\latexignore{\rtfignore{\wxheading{Function groups}}}
152
153\membersection{Construction}\label{wxcmdlineparserconstruction}
154
155Before \helpref{Parse}{wxcmdlineparserparse} can be called, the command line
156parser object must have the command line to parse and also the rules saying
157which switches, options and parameters are valid - this is called command line
158description in what follows.
159
160You have complete freedom of choice as to when specify the required information,
161the only restriction is that it must be done before calling
162\helpref{Parse}{wxcmdlineparserparse}.
163
164To specify the command line to parse you may use either one of constructors
165accepting it (\helpref{wxCmdLineParser(argc, argv)}{wxcmdlineparserwxcmdlineparserargc} or
166\helpref{wxCmdLineParser}{wxcmdlineparserwxcmdlineparserdescargc} usually) or,
167if you use \helpref{the default constructor}{wxcmdlineparserwxcmdlineparserdef},
168you can do it later by calling
169\helpref{SetCmdLine}{wxcmdlineparsersetcmdlineargc}.
170
171The same holds for command line description: it can be specified either in
172the constructor (\helpref{without command line}{wxcmdlineparserwxcmdlineparserdesc} or
173\helpref{together with it}{wxcmdlineparserwxcmdlineparserdescargc}) or
174constructed later using either \helpref{SetDesc}{wxcmdlineparsersetdesc} or
175combination of \helpref{AddSwitch}{wxcmdlineparseraddswitch},
176\helpref{AddOption}{wxcmdlineparseraddoption} and
177\helpref{AddParam}{wxcmdlineparseraddparam} methods.
178
179Using constructors or \helpref{SetDesc}{wxcmdlineparsersetdesc} uses a (usually
180{\tt const static}) table containing the command line description. If you want
181to decide which options to accept during the run-time, using one of the
182{\tt AddXXX()} functions above might be preferable.
183
184\membersection{Customization}\label{wxcmdlineparsercustomization}
185
186wxCmdLineParser has several global options which may be changed by the
187application. All of the functions described in this section should be called
188before \helpref{Parse}{wxcmdlineparserparse}.
189
190First global option is the support for long (also known as GNU-style) options.
191The long options are the ones which start with two dashes ({\tt "--"}) and look
192like this: {\tt --verbose}, i.e. they generally are complete words and not some
193abbreviations of them. As long options are used by more and more applications,
194they are enabled by default, but may be disabled with
195\helpref{DisableLongOptions}{wxcmdlineparserdisablelongoptions}.
196
197Another global option is the set of characters which may be used to start an
198option (otherwise, the word on the command line is assumed to be a parameter).
199Under Unix, {\tt '-'} is always used, but Windows has at least two common
200choices for this: {\tt '-'} and {\tt '/'}. Some programs also use {\tt '+'}.
201The default is to use what suits most the current platform, but may be changed
202with \helpref{SetSwitchChars}{wxcmdlineparsersetswitchchars} method.
203
204Finally, \helpref{SetLogo}{wxcmdlineparsersetlogo} can be used to show some
205application-specific text before the explanation given by
206\helpref{Usage}{wxcmdlineparserusage} function.
207
208\membersection{Parsing command line}\label{wxcmdlineparserparsing}
209
210After the command line description was constructed and the desired options were
211set, you can finally call \helpref{Parse}{wxcmdlineparserparse} method.
212It returns $0$ if the command line was correct and was parsed, $-1$ if the help
213option was specified (this is a separate case as, normally, the program will
214terminate after this) or a positive number if there was an error during the
215command line parsing.
216
217In the latter case, the appropriate error message and usage information are
218logged by wxCmdLineParser itself using the standard wxWidgets logging functions.
219
220\membersection{Getting results}\label{wxcmdlineparsergettingresults}
221
222After calling \helpref{Parse}{wxcmdlineparserparse} (and if it returned $0$),
223you may access the results of parsing using one of overloaded {\tt Found()}
224methods.
225
226For a simple switch, you will simply call
227\helpref{Found}{wxcmdlineparserfoundswitch} to determine if the switch was given
228or not, for an option or a parameter, you will call a version of {\tt Found()}
229which also returns the associated value in the provided variable. All
230{\tt Found()} functions return true if the switch or option were found in the
231command line or false if they were not specified.
232
233%%%%%%%%%%%%% Methods in alphabetic order %%%%%%%%%%%%%
234\helponly{\insertatlevel{2}{
235
236\wxheading{Members}
237
238}}
239
240\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparserdef}
241
242\func{}{wxCmdLineParser}{\void}
243
244Default constructor. You must use
245\helpref{SetCmdLine}{wxcmdlineparsersetcmdlineargc} later.
246
247\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparserargc}
248
249\func{}{wxCmdLineParser}{\param{int }{argc}, \param{char** }{argv}}
250
251Constructor specifies the command line to parse. This is the traditional
252(Unix) command line format. The parameters {\it argc} and {\it argv} have the
253same meaning as for {\tt main()} function.
254
255\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparserstr}
256
257\func{}{wxCmdLineParser}{\param{const wxString\& }{cmdline}}
258
259Constructor specifies the command line to parse in Windows format. The parameter
260{\it cmdline} has the same meaning as the corresponding parameter of
261{\tt WinMain()}.
262
263\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparserdesc}
264
265\func{}{wxCmdLineParser}{\param{const wxCmdLineEntryDesc* }{desc}}
266
267Same as \helpref{wxCmdLineParser}{wxcmdlineparserwxcmdlineparserdef}, but also
268specifies the \helpref{command line description}{wxcmdlineparsersetdesc}.
269
270\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparserdescargc}
271
272\func{}{wxCmdLineParser}{\param{const wxCmdLineEntryDesc* }{desc}, \param{int }{argc}, \param{char** }{argv}}
273
274Same as \helpref{wxCmdLineParser}{wxcmdlineparserwxcmdlineparserargc}, but also
275specifies the \helpref{command line description}{wxcmdlineparsersetdesc}.
276
277\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparserdescstr}
278
279\func{}{wxCmdLineParser}{\param{const wxCmdLineEntryDesc* }{desc}, \param{const wxString\& }{cmdline}}
280
281Same as \helpref{wxCmdLineParser}{wxcmdlineparserwxcmdlineparserstr}, but also
282specifies the \helpref{command line description}{wxcmdlineparsersetdesc}.
283
284\membersection{wxCmdLineParser::ConvertStringToArgs}\label{wxcmdlineparserconvertstringtoargs}
285
286\func{static wxArrayString}{ConvertStringToArgs}{\param{const wxChar }{*cmdline}}
287
288Breaks down the string containing the full command line in words. The words are
289separated by whitespace. The quotes can be used in the input string to quote
290the white space and the back slashes can be used to quote the quotes.
291
292\membersection{wxCmdLineParser::SetCmdLine}\label{wxcmdlineparsersetcmdlineargc}
293
294\func{void}{SetCmdLine}{\param{int }{argc}, \param{char** }{argv}}
295
296Set command line to parse after using one of the constructors which don't do it.
297
298\wxheading{See also}
299
300\helpref{wxCmdLineParser}{wxcmdlineparserwxcmdlineparserargc}
301
302\membersection{wxCmdLineParser::SetCmdLine}\label{wxcmdlineparsersetcmdlinestr}
303
304\func{void}{SetCmdLine}{\param{const wxString\& }{cmdline}}
305
306Set command line to parse after using one of the constructors which don't do it.
307
308\wxheading{See also}
309
310\helpref{wxCmdLineParser}{wxcmdlineparserwxcmdlineparserstr}
311
312\membersection{wxCmdLineParser::\destruct{wxCmdLineParser}}\label{wxcmdlineparserdtor}
313
314\func{}{\destruct{wxCmdLineParser}}{\void}
315
316Frees resources allocated by the object.
317
318{\bf NB:} destructor is not virtual, don't use this class polymorphically.
319
320\membersection{wxCmdLineParser::SetSwitchChars}\label{wxcmdlineparsersetswitchchars}
321
322\func{void}{SetSwitchChars}{\param{const wxString\& }{switchChars}}
323
324{\it switchChars} contains all characters with which an option or switch may
325start. Default is {\tt "-"} for Unix, {\tt "-/"} for Windows.
326
327\membersection{wxCmdLineParser::EnableLongOptions}\label{wxcmdlineparserenablelongoptions}
328
329\func{void}{EnableLongOptions}{\param{bool }{enable = true}}
330
331Enable or disable support for the long options.
332
333As long options are not (yet) POSIX-compliant, this option allows to disable
334them.
335
336\wxheading{See also}
337
338\helpref{Customization}{wxcmdlineparsercustomization} and \helpref{AreLongOptionsEnabled}{wxcmdlineparserarelongoptionsenabled}
339
340\membersection{wxCmdLineParser::DisableLongOptions}\label{wxcmdlineparserdisablelongoptions}
341
342\func{void}{DisableLongOptions}{\void}
343
344Identical to \helpref{EnableLongOptions(false)}{wxcmdlineparserenablelongoptions}.
345
346\membersection{wxCmdLineParser::AreLongOptionsEnabled}\label{wxcmdlineparserarelongoptionsenabled}
347
348\func{bool}{AreLongOptionsEnabled}{\void}
349
350Returns true if long options are enabled, otherwise false.
351
352\wxheading{See also}
353
354\helpref{EnableLongOptions}{wxcmdlineparserenablelongoptions}
355
356\membersection{wxCmdLineParser::SetLogo}\label{wxcmdlineparsersetlogo}
357
358\func{void}{SetLogo}{\param{const wxString\& }{logo}}
359
360{\it logo} is some extra text which will be shown by
361\helpref{Usage}{wxcmdlineparserusage} method.
362
363\membersection{wxCmdLineParser::SetDesc}\label{wxcmdlineparsersetdesc}
364
365\func{void}{SetDesc}{\param{const wxCmdLineEntryDesc* }{desc}}
366
367Construct the command line description
368
369Take the command line description from the wxCMD\_LINE\_NONE terminated table.
370
371Example of usage:
372
373\begin{verbatim}
374static const wxCmdLineEntryDesc cmdLineDesc[] =
375{
376 { wxCMD_LINE_SWITCH, "v", "verbose", "be verbose" },
377 { wxCMD_LINE_SWITCH, "q", "quiet", "be quiet" },
378
379 { wxCMD_LINE_OPTION, "o", "output", "output file" },
380 { wxCMD_LINE_OPTION, "i", "input", "input dir" },
381 { wxCMD_LINE_OPTION, "s", "size", "output block size", wxCMD_LINE_VAL_NUMBER },
382 { wxCMD_LINE_OPTION, "d", "date", "output file date", wxCMD_LINE_VAL_DATE },
383
384 { wxCMD_LINE_PARAM, NULL, NULL, "input file", wxCMD_LINE_VAL_STRING, wxCMD_LINE_PARAM_MULTIPLE },
385
386 { wxCMD_LINE_NONE }
387};
388
389wxCmdLineParser parser;
390
391parser.SetDesc(cmdLineDesc);
392\end{verbatim}
393
394\membersection{wxCmdLineParser::AddSwitch}\label{wxcmdlineparseraddswitch}
395
396\func{void}{AddSwitch}{\param{const wxString\& }{name}, \param{const wxString\& }{lng = wxEmptyString}, \param{const wxString\& }{desc = wxEmptyString}, \param{int }{flags = 0}}
397
398Add a switch {\it name} with an optional long name {\it lng} (no long name if it
399is empty, which is default), description {\it desc} and flags {\it flags} to the
400command line description.
401
402\membersection{wxCmdLineParser::AddOption}\label{wxcmdlineparseraddoption}
403
404\func{void}{AddOption}{\param{const wxString\& }{name}, \param{const wxString\& }{lng = wxEmptyString}, \param{const wxString\& }{desc = wxEmptyString}, \param{wxCmdLineParamType }{type = wxCMD\_LINE\_VAL\_STRING}, \param{int }{flags = 0}}
405
406Add an option {\it name} with an optional long name {\it lng} (no long name if
407it is empty, which is default) taking a value of the given type (string by
408default) to the command line description.
409
410\membersection{wxCmdLineParser::AddParam}\label{wxcmdlineparseraddparam}
411
412\func{void}{AddParam}{\param{const wxString\& }{desc = wxEmptyString}, \param{wxCmdLineParamType }{type = wxCMD\_LINE\_VAL\_STRING}, \param{int }{flags = 0}}
413
414Add a parameter of the given {\it type} to the command line description.
415
416\membersection{wxCmdLineParser::Parse}\label{wxcmdlineparserparse}
417
418\func{int}{Parse}{\param{bool }{giveUsage = {\tt true}}}
419
420Parse the command line, return $0$ if ok, $-1$ if {\tt "-h"} or {\tt "--help"}
421option was encountered and the help message was given or a positive value if a
422syntax error occured.
423
424\wxheading{Parameters}
425
426\docparam{giveUsage}{If {\tt true} (default), the usage message is given if a
427syntax error was encountered while parsing the command line or if help was
428requested. If {\tt false}, only error messages about possible syntax errors
429are given, use \helpref{Usage}{wxcmdlineparserusage} to show the usage message
430from the caller if needed.}
431
432\membersection{wxCmdLineParser::Usage}\label{wxcmdlineparserusage}
433
434\func{void}{Usage}{\void}
435
436Give the standard usage message describing all program options. It will use the
437options and parameters descriptions specified earlier, so the resulting message
438will not be helpful to the user unless the descriptions were indeed specified.
439
440\wxheading{See also}
441
442\helpref{SetLogo}{wxcmdlineparsersetlogo}
443
444\membersection{wxCmdLineParser::Found}\label{wxcmdlineparserfoundswitch}
445
446\constfunc{bool}{Found}{\param{const wxString\& }{name}}
447
448Returns true if the given switch was found, false otherwise.
449
450\membersection{wxCmdLineParser::Found}\label{wxcmdlineparserfoundstringoption}
451
452\constfunc{bool}{Found}{\param{const wxString\& }{name}, \param{wxString* }{value}}
453
454Returns true if an option taking a string value was found and stores the
455value in the provided pointer (which should not be NULL).
456
457\membersection{wxCmdLineParser::Found}\label{wxcmdlineparserfoundintoption}
458
459\constfunc{bool}{Found}{\param{const wxString\& }{name}, \param{long* }{value}}
460
461Returns true if an option taking an integer value was found and stores
462the value in the provided pointer (which should not be NULL).
463
464\membersection{wxCmdLineParser::Found}\label{wxcmdlineparserfounddateoption}
465
466\constfunc{bool}{Found}{\param{const wxString\& }{name}, \param{wxDateTime* }{value}}
467
468Returns true if an option taking a date value was found and stores the
469value in the provided pointer (which should not be NULL).
470
471\membersection{wxCmdLineParser::GetParamCount}\label{wxcmdlineparsergetparamcount}
472
473\constfunc{size\_t}{GetParamCount}{\void}
474
475Returns the number of parameters found. This function makes sense mostly if you
476had used {\tt wxCMD\_LINE\_PARAM\_MULTIPLE} flag.
477
478\membersection{wxCmdLineParser::GetParam}\label{wxcmdlineparsergetparam}
479
480\constfunc{wxString}{GetParam}{\param{size\_t }{n = 0u}}
481
482Returns the value of Nth parameter (as string only for now).
483
484\wxheading{See also}
485
486\helpref{GetParamCount}{wxcmdlineparsergetparamcount}
487