]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/latex/wx/cmdlpars.tex
Wine fixes
[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: wxWindows license
10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11
12\section{\class{wxCmdLineParser}}\label{wxcmdlineparser}
13
14wxCmdLineParser is a class for parsing the 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
154\membersection{Construction}\label{wxcmdlineparserconstruction}
155
156Before \helpref{Parse}{wxcmdlineparserparse} can be called, the command line
157parser object must have the command line to parse and also the rules saying
158which switches, options and parameters are valid - this is called command line
159description in what follows.
160
161You have complete freedom of choice as to when specify the required information,
162the only restriction is that it must be done before calling
163\helpref{Parse}{wxcmdlineparserparse}.
164
165To specify the command line to parse you may use either one of constructors
166accepting it (\helpref{wxCmdLineParser(argc, argv)}{wxcmdlineparserwxcmdlineparserargc} or
167\helpref{wxCmdLineParser}{wxcmdlineparserwxcmdlineparserdescargc} usually) or,
168if you use \helpref{the default constructor}{wxcmdlineparserwxcmdlineparserdef},
169you can do it later by calling
170\helpref{SetCmdLine}{wxcmdlineparsersetcmdlineargc}.
171
172The same holds for command line description: it can be specified either in
173the constructor (\helpref{without command line}{wxcmdlineparserwxcmdlineparserdesc} or
174\helpref{together with it}{wxcmdlineparserwxcmdlineparserdescargc}) or
175constructed later using either \helpref{SetDesc}{wxcmdlineparsersetdesc} or
176combination of \helpref{AddSwitch}{wxcmdlineparseraddswitch},
177\helpref{AddOption}{wxcmdlineparseraddoption} and
178\helpref{AddParam}{wxcmdlineparseraddparam} methods.
179
180Using constructors or \helpref{SetDesc}{wxcmdlineparsersetdesc} uses a (usually
181{\tt const static}) table containing the command line description. If you want
182to decide which options to accept during the run-time, using one of the
183{\tt AddXXX()} functions above might be preferable.
184
185
186\membersection{Customization}\label{wxcmdlineparsercustomization}
187
188wxCmdLineParser has several global options which may be changed by the
189application. All of the functions described in this section should be called
190before \helpref{Parse}{wxcmdlineparserparse}.
191
192First global option is the support for long (also known as GNU-style) options.
193The long options are the ones which start with two dashes ({\tt "--"}) and look
194like this: {\tt --verbose}, i.e. they generally are complete words and not some
195abbreviations of them. As long options are used by more and more applications,
196they are enabled by default, but may be disabled with
197\helpref{DisableLongOptions}{wxcmdlineparserdisablelongoptions}.
198
199Another global option is the set of characters which may be used to start an
200option (otherwise, the word on the command line is assumed to be a parameter).
201Under Unix, {\tt '-'} is always used, but Windows has at least two common
202choices for this: {\tt '-'} and {\tt '/'}. Some programs also use {\tt '+'}.
203The default is to use what suits most the current platform, but may be changed
204with \helpref{SetSwitchChars}{wxcmdlineparsersetswitchchars} method.
205
206Finally, \helpref{SetLogo}{wxcmdlineparsersetlogo} can be used to show some
207application-specific text before the explanation given by
208\helpref{Usage}{wxcmdlineparserusage} function.
209
210
211\membersection{Parsing command line}\label{wxcmdlineparserparsing}
212
213After the command line description was constructed and the desired options were
214set, you can finally call \helpref{Parse}{wxcmdlineparserparse} method.
215It returns $0$ if the command line was correct and was parsed, $-1$ if the help
216option was specified (this is a separate case as, normally, the program will
217terminate after this) or a positive number if there was an error during the
218command line parsing.
219
220In the latter case, the appropriate error message and usage information are
221logged by wxCmdLineParser itself using the standard wxWidgets logging functions.
222
223
224\membersection{Getting results}\label{wxcmdlineparsergettingresults}
225
226After calling \helpref{Parse}{wxcmdlineparserparse} (and if it returned $0$),
227you may access the results of parsing using one of overloaded {\tt Found()}
228methods.
229
230For a simple switch, you will simply call
231\helpref{Found}{wxcmdlineparserfoundswitch} to determine if the switch was given
232or not, for an option or a parameter, you will call a version of {\tt Found()}
233which also returns the associated value in the provided variable. All
234{\tt Found()} functions return true if the switch or option were found in the
235command line or false if they were not specified.
236
237%%%%%%%%%%%%% Methods in alphabetic order %%%%%%%%%%%%%
238\helponly{\insertatlevel{2}{
239
240\wxheading{Members}
241
242}}
243
244
245\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparserdef}
246
247\func{}{wxCmdLineParser}{\void}
248
249Default constructor. You must use
250\helpref{SetCmdLine}{wxcmdlineparsersetcmdlineargc} later.
251
252
253\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparserargc}
254
255\func{}{wxCmdLineParser}{\param{int }{argc}, \param{char** }{argv}}
256
257\func{}{wxCmdLineParser}{\param{int }{argc}, \param{wchar\_t** }{argv}}
258
259Constructor specifies the command line to parse. This is the traditional
260(Unix) command line format. The parameters {\it argc} and {\it argv} have the
261same meaning as for {\tt main()} function.
262
263The second overloaded constructor is only available in Unicode build. The
264first one is available in both ANSI and Unicode modes because under some
265platforms the command line arguments are passed as ASCII strings even to
266Unicode programs.
267
268
269\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparserstr}
270
271\func{}{wxCmdLineParser}{\param{const wxString\& }{cmdline}}
272
273Constructor specifies the command line to parse in Windows format. The parameter
274{\it cmdline} has the same meaning as the corresponding parameter of
275{\tt WinMain()}.
276
277
278\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparserdesc}
279
280\func{}{wxCmdLineParser}{\param{const wxCmdLineEntryDesc* }{desc}}
281
282Same as \helpref{wxCmdLineParser}{wxcmdlineparserwxcmdlineparserdef}, but also
283specifies the \helpref{command line description}{wxcmdlineparsersetdesc}.
284
285
286\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparserdescargc}
287
288\func{}{wxCmdLineParser}{\param{const wxCmdLineEntryDesc* }{desc}, \param{int }{argc}, \param{char** }{argv}}
289
290Same as \helpref{wxCmdLineParser}{wxcmdlineparserwxcmdlineparserargc}, but also
291specifies the \helpref{command line description}{wxcmdlineparsersetdesc}.
292
293
294\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparserdescstr}
295
296\func{}{wxCmdLineParser}{\param{const wxCmdLineEntryDesc* }{desc}, \param{const wxString\& }{cmdline}}
297
298Same as \helpref{wxCmdLineParser}{wxcmdlineparserwxcmdlineparserstr}, but also
299specifies the \helpref{command line description}{wxcmdlineparsersetdesc}.
300
301
302\membersection{wxCmdLineParser::ConvertStringToArgs}\label{wxcmdlineparserconvertstringtoargs}
303
304\func{static wxArrayString}{ConvertStringToArgs}{\param{const wxChar }{*cmdline}}
305
306Breaks down the string containing the full command line in words. The words are
307separated by whitespace. The quotes can be used in the input string to quote
308the white space and the back slashes can be used to quote the quotes.
309
310
311\membersection{wxCmdLineParser::SetCmdLine}\label{wxcmdlineparsersetcmdlineargc}
312
313\func{void}{SetCmdLine}{\param{int }{argc}, \param{char** }{argv}}
314
315\func{void}{SetCmdLine}{\param{int }{argc}, \param{wchar\_t** }{argv}}
316
317Set command line to parse after using one of the constructors which don't do it.
318The second overload of this function is only available in Unicode build.
319
320\wxheading{See also}
321
322\helpref{wxCmdLineParser}{wxcmdlineparserwxcmdlineparserargc}
323
324
325\membersection{wxCmdLineParser::SetCmdLine}\label{wxcmdlineparsersetcmdlinestr}
326
327\func{void}{SetCmdLine}{\param{const wxString\& }{cmdline}}
328
329Set command line to parse after using one of the constructors which don't do it.
330
331\wxheading{See also}
332
333\helpref{wxCmdLineParser}{wxcmdlineparserwxcmdlineparserstr}
334
335
336\membersection{wxCmdLineParser::\destruct{wxCmdLineParser}}\label{wxcmdlineparserdtor}
337
338\func{}{\destruct{wxCmdLineParser}}{\void}
339
340Frees resources allocated by the object.
341
342{\bf NB:} destructor is not virtual, don't use this class polymorphically.
343
344
345\membersection{wxCmdLineParser::SetSwitchChars}\label{wxcmdlineparsersetswitchchars}
346
347\func{void}{SetSwitchChars}{\param{const wxString\& }{switchChars}}
348
349{\it switchChars} contains all characters with which an option or switch may
350start. Default is {\tt "-"} for Unix, {\tt "-/"} for Windows.
351
352
353\membersection{wxCmdLineParser::EnableLongOptions}\label{wxcmdlineparserenablelongoptions}
354
355\func{void}{EnableLongOptions}{\param{bool }{enable = true}}
356
357Enable or disable support for the long options.
358
359As long options are not (yet) POSIX-compliant, this option allows to disable
360them.
361
362\wxheading{See also}
363
364\helpref{Customization}{wxcmdlineparsercustomization} and \helpref{AreLongOptionsEnabled}{wxcmdlineparserarelongoptionsenabled}
365
366
367\membersection{wxCmdLineParser::DisableLongOptions}\label{wxcmdlineparserdisablelongoptions}
368
369\func{void}{DisableLongOptions}{\void}
370
371Identical to \helpref{EnableLongOptions(false)}{wxcmdlineparserenablelongoptions}.
372
373
374\membersection{wxCmdLineParser::AreLongOptionsEnabled}\label{wxcmdlineparserarelongoptionsenabled}
375
376\func{bool}{AreLongOptionsEnabled}{\void}
377
378Returns true if long options are enabled, otherwise false.
379
380\wxheading{See also}
381
382\helpref{EnableLongOptions}{wxcmdlineparserenablelongoptions}
383
384
385\membersection{wxCmdLineParser::SetLogo}\label{wxcmdlineparsersetlogo}
386
387\func{void}{SetLogo}{\param{const wxString\& }{logo}}
388
389{\it logo} is some extra text which will be shown by
390\helpref{Usage}{wxcmdlineparserusage} method.
391
392
393\membersection{wxCmdLineParser::SetDesc}\label{wxcmdlineparsersetdesc}
394
395\func{void}{SetDesc}{\param{const wxCmdLineEntryDesc* }{desc}}
396
397Construct the command line description
398
399Take the command line description from the wxCMD\_LINE\_NONE terminated table.
400
401Example of usage:
402
403\begin{verbatim}
404static const wxCmdLineEntryDesc cmdLineDesc[] =
405{
406 { wxCMD_LINE_SWITCH, "v", "verbose", "be verbose" },
407 { wxCMD_LINE_SWITCH, "q", "quiet", "be quiet" },
408
409 { wxCMD_LINE_OPTION, "o", "output", "output file" },
410 { wxCMD_LINE_OPTION, "i", "input", "input dir" },
411 { wxCMD_LINE_OPTION, "s", "size", "output block size", wxCMD_LINE_VAL_NUMBER },
412 { wxCMD_LINE_OPTION, "d", "date", "output file date", wxCMD_LINE_VAL_DATE },
413
414 { wxCMD_LINE_PARAM, NULL, NULL, "input file", wxCMD_LINE_VAL_STRING, wxCMD_LINE_PARAM_MULTIPLE },
415
416 { wxCMD_LINE_NONE }
417};
418
419wxCmdLineParser parser;
420
421parser.SetDesc(cmdLineDesc);
422\end{verbatim}
423
424
425\membersection{wxCmdLineParser::AddSwitch}\label{wxcmdlineparseraddswitch}
426
427\func{void}{AddSwitch}{\param{const wxString\& }{name}, \param{const wxString\& }{lng = wxEmptyString}, \param{const wxString\& }{desc = wxEmptyString}, \param{int }{flags = 0}}
428
429Add a switch {\it name} with an optional long name {\it lng} (no long name if it
430is empty, which is default), description {\it desc} and flags {\it flags} to the
431command line description.
432
433
434\membersection{wxCmdLineParser::AddOption}\label{wxcmdlineparseraddoption}
435
436\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}}
437
438Add an option {\it name} with an optional long name {\it lng} (no long name if
439it is empty, which is default) taking a value of the given type (string by
440default) to the command line description.
441
442
443\membersection{wxCmdLineParser::AddParam}\label{wxcmdlineparseraddparam}
444
445\func{void}{AddParam}{\param{const wxString\& }{desc = wxEmptyString}, \param{wxCmdLineParamType }{type = wxCMD\_LINE\_VAL\_STRING}, \param{int }{flags = 0}}
446
447Add a parameter of the given {\it type} to the command line description.
448
449
450\membersection{wxCmdLineParser::Parse}\label{wxcmdlineparserparse}
451
452\func{int}{Parse}{\param{bool }{giveUsage = {\tt true}}}
453
454Parse the command line, return $0$ if ok, $-1$ if {\tt "-h"} or {\tt "--help"}
455option was encountered and the help message was given or a positive value if a
456syntax error occurred.
457
458\wxheading{Parameters}
459
460\docparam{giveUsage}{If {\tt true} (default), the usage message is given if a
461syntax error was encountered while parsing the command line or if help was
462requested. If {\tt false}, only error messages about possible syntax errors
463are given, use \helpref{Usage}{wxcmdlineparserusage} to show the usage message
464from the caller if needed.}
465
466
467\membersection{wxCmdLineParser::Usage}\label{wxcmdlineparserusage}
468
469\func{void}{Usage}{\void}
470
471Give the standard usage message describing all program options. It will use the
472options and parameters descriptions specified earlier, so the resulting message
473will not be helpful to the user unless the descriptions were indeed specified.
474
475\wxheading{See also}
476
477\helpref{SetLogo}{wxcmdlineparsersetlogo}
478
479
480\membersection{wxCmdLineParser::Found}\label{wxcmdlineparserfoundswitch}
481
482\constfunc{bool}{Found}{\param{const wxString\& }{name}}
483
484Returns true if the given switch was found, false otherwise.
485
486
487\membersection{wxCmdLineParser::Found}\label{wxcmdlineparserfoundstringoption}
488
489\constfunc{bool}{Found}{\param{const wxString\& }{name}, \param{wxString* }{value}}
490
491Returns true if an option taking a string value was found and stores the
492value in the provided pointer (which should not be NULL).
493
494
495\membersection{wxCmdLineParser::Found}\label{wxcmdlineparserfoundintoption}
496
497\constfunc{bool}{Found}{\param{const wxString\& }{name}, \param{long* }{value}}
498
499Returns true if an option taking an integer value was found and stores
500the value in the provided pointer (which should not be NULL).
501
502
503\membersection{wxCmdLineParser::Found}\label{wxcmdlineparserfounddateoption}
504
505\constfunc{bool}{Found}{\param{const wxString\& }{name}, \param{wxDateTime* }{value}}
506
507Returns true if an option taking a date value was found and stores the
508value in the provided pointer (which should not be NULL).
509
510
511\membersection{wxCmdLineParser::GetParamCount}\label{wxcmdlineparsergetparamcount}
512
513\constfunc{size\_t}{GetParamCount}{\void}
514
515Returns the number of parameters found. This function makes sense mostly if you
516had used {\tt wxCMD\_LINE\_PARAM\_MULTIPLE} flag.
517
518
519\membersection{wxCmdLineParser::GetParam}\label{wxcmdlineparsergetparam}
520
521\constfunc{wxString}{GetParam}{\param{size\_t }{n = 0u}}
522
523Returns the value of Nth parameter (as string only for now).
524
525\wxheading{See also}
526
527\helpref{GetParamCount}{wxcmdlineparsergetparamcount}
528