1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 %% Purpose: wxCmdLineParser documentation
4 %% Author: Vadim Zeitlin
8 %% Copyright: (c) Vadim Zeitlin
9 %% License: wxWindows license
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
12 \section{\class{wxCmdLineParser
}}\label{wxcmdlineparser
}
14 wxCmdLineParser is a class for parsing command line.
16 It has the following features:
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$).
25 To use it you should follow these steps:
27 \begin{enumerate
}\itemsep=
0pt
28 \item \helpref{construct
}{wxcmdlineparserconstruction
} an object of this class
29 giving 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
35 In the documentation below the following terminology is used:
37 \begin{twocollist
}\itemsep=
0pt
38 \twocolitem{switch
}{This is a boolean option which can be given or not, but
39 which doesn't have any value. We use the word switch to distinguish such boolean
40 options 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
43 unlike a switch. For example,
{\tt -o:filename
} might be an option which allows
44 to specify the name of the output file.
}
45 \twocolitem{parameter
}{This is a required program argument.
}
48 \wxheading{Derived from
}
52 \wxheading{Include files
}
58 The structure wxCmdLineEntryDesc is used to describe the one command
59 line switch, option or parameter. An array of such structures should be passed
60 to
\helpref{SetDesc()
}{wxcmdlineparsersetdesc
}. Also, the meanings of parameters
61 of the
{\tt AddXXX()
} functions are the same as of the corresponding fields in
65 struct wxCmdLineEntryDesc
67 wxCmdLineEntryType kind;
68 const wxChar *shortName;
69 const wxChar *longName;
70 const wxChar *description;
71 wxCmdLineParamType type;
76 The type of a command line entity is in the
{\tt kind
} field and may be one of
77 the following constants:
81 enum wxCmdLineEntryType
86 wxCMD
\_LINE\_NONE // use this to terminate the list
90 The field
{\tt shortName
} is the usual, short, name of the switch or the option.
91 {\tt longName
} is the corresponding long name or NULL if the option has no long
92 name. Both of these fields are unused for the parameters. Both the short and
93 long option names can contain only letters, digits and the underscores.
95 {\tt description
} is used by the
\helpref{Usage()
}{wxcmdlineparserusage
} method
96 to construct a help message explaining the syntax of the program.
98 The possible values of
{\tt type
} which specifies the type of the value accepted
99 by an option or parameter are:
103 enum wxCmdLineParamType
105 wxCMD
\_LINE\_VAL\_STRING, // default
106 wxCMD
\_LINE\_VAL\_NUMBER,
107 wxCMD
\_LINE\_VAL\_DATE,
108 wxCMD
\_LINE\_VAL\_NONE
112 Finally, the
{\tt flags
} field is a combination of the following bit masks:
118 wxCMD
\_LINE\_OPTION\_MANDATORY =
0x01, // this option must be given
119 wxCMD
\_LINE\_PARAM\_OPTIONAL =
0x02, // the parameter may be omitted
120 wxCMD
\_LINE\_PARAM\_MULTIPLE =
0x04, // the parameter may be repeated
121 wxCMD
\_LINE\_OPTION\_HELP =
0x08, // this option is a help request
122 wxCMD
\_LINE\_NEEDS\_SEPARATOR =
0x10, // must have sep before the value
126 Notice that by default (i.e. if flags are just $
0$), options are optional (sic)
127 and each call to
\helpref{AddParam()
}{wxcmdlineparseraddparam
} allows one more
128 parameter - this may be changed by giving non-default flags to it, i.e. use
129 {\tt wxCMD
\_LINE\_OPTION\_MANDATORY} to require that the option is given and
130 {\tt wxCMD
\_LINE\_PARAM\_OPTIONAL} to make a parameter optional. Also,
131 {\tt wxCMD
\_LINE\_PARAM\_MULTIPLE} may be specified if the programs accepts a
132 variable number of parameters - but it only can be given for the last parameter
133 in the command line description. If you use this flag, you will probably need to
134 use
\helpref{GetParamCount
}{wxcmdlineparsergetparamcount
} to retrieve the number
135 of parameters effectively specified after calling
136 \helpref{Parse
}{wxcmdlineparserparse
}.
138 The last flag
{\tt wxCMD
\_LINE\_NEEDS\_SEPARATOR} can be specified to require a
139 separator (either a colon, an equal sign or white space) between the option
140 name and its value. By default, no separator is required.
144 \helpref{wxApp::argc
}{wxappargc
} and
\helpref{wxApp::argv
}{wxappargv
}\\
147 %%%%%%%%%%%%% Methods by group %%%%%%%%%%%%%
148 \latexignore{\rtfignore{\wxheading{Function groups
}}}
150 \membersection{Construction
}\label{wxcmdlineparserconstruction
}
152 Before
\helpref{Parse
}{wxcmdlineparserparse
} can be called, the command line
153 parser object must have the command line to parse and also the rules saying
154 which switches, options and parameters are valid - this is called command line
155 description in what follows.
157 You have complete freedom of choice as to when specify the required information,
158 the only restriction is that it must be done before calling
159 \helpref{Parse
}{wxcmdlineparserparse
}.
161 To specify the command line to parse you may use either one of constructors
162 accepting it (
\helpref{wxCmdLineParser(argc, argv)
}{wxcmdlineparserwxcmdlineparserargc
} or
163 \helpref{wxCmdLineParser
}{wxcmdlineparserwxcmdlineparserdescargc
} usually) or,
164 if you use
\helpref{the default constructor
}{wxcmdlineparserwxcmdlineparserdef
},
165 you can do it later by calling
166 \helpref{SetCmdLine
}{wxcmdlineparsersetcmdlineargc
}.
168 The same holds for command line description: it can be specified either in
169 the constructor (
\helpref{without command line
}{wxcmdlineparserwxcmdlineparserdesc
} or
170 \helpref{together with it
}{wxcmdlineparserwxcmdlineparserdescargc
}) or
171 constructed later using either
\helpref{SetDesc
}{wxcmdlineparsersetdesc
} or
172 combination of
\helpref{AddSwitch
}{wxcmdlineparseraddswitch
},
173 \helpref{AddOption
}{wxcmdlineparseraddoption
} and
174 \helpref{AddParam
}{wxcmdlineparseraddparam
} methods.
176 Using constructors or
\helpref{SetDesc
}{wxcmdlineparsersetdesc
} uses a (usually
177 {\tt const static
}) table containing the command line description. If you want
178 to decide which options to acccept during the run-time, using one of the
179 {\tt AddXXX()
} functions above might be preferable.
181 \membersection{Customization
}\label{wxcmdlineparsercustomization
}
183 wxCmdLineParser has several global options which may be changed by the
184 application. All of the functions described in this section should be called
185 before
\helpref{Parse
}{wxcmdlineparserparse
}.
187 First global option is the support for long (also known as GNU-style) options.
188 The long options are the ones which start with two dashes (
{\tt "--"
}) and look
189 like this:
{\tt --verbose
}, i.e. they generally are complete words and not some
190 abbreviations of them. As long options are used by more and more applications,
191 they are enabled by default, but may be disabled with
192 \helpref{DisableLongOptions
}{wxcmdlineparserdisablelongoptions
}.
194 Another global option is the set of characters which may be used to start an
195 option (otherwise, the word on the command line is assumed to be a parameter).
196 Under Unix,
{\tt '-'
} is always used, but Windows has at least two common
197 choices for this:
{\tt '-'
} and
{\tt '/'
}. Some programs also use
{\tt '+'
}.
198 The default is to use what suits most the current platform, but may be changed
199 with
\helpref{SetSwitchChars
}{wxcmdlineparsersetswitchchars
} method.
201 Finally,
\helpref{SetLogo
}{wxcmdlineparsersetlogo
} can be used to show some
202 application-specific text before the explanation given by
203 \helpref{Usage
}{wxcmdlineparserusage
} function.
205 \membersection{Parsing command line
}\label{wxcmdlineparserparsing
}
207 After the command line description was constructed and the desired options were
208 set, you can finally call
\helpref{Parse
}{wxcmdlineparserparse
} method.
209 It returns $
0$ if the command line was correct and was parsed, $-
1$ if the help
210 option was specified (this is a separate case as, normally, the program will
211 terminate after this) or a positive number if there was an error during the
212 command line parsing.
214 In the latter case, the appropriate error message and usage information are
215 logged by wxCmdLineParser itself using the standard wxWindows logging functions.
217 \membersection{Getting results
}\label{wxcmdlineparsergettingresults
}
219 After calling
\helpref{Parse
}{wxcmdlineparserparse
} (and if it returned $
0$),
220 you may access the results of parsing using one of overloaded
{\tt Found()
}
223 For a simple switch, you will simply call
224 \helpref{Found
}{wxcmdlineparserfoundswitch
} to determine if the switch was given
225 or not, for an option or a parameter, you will call a version of
{\tt Found()
}
226 which also returns the associated value in the provided variable. All
227 {\tt Found()
} functions return TRUE if the switch or option were found in the
228 command line or FALSE if they were not specified.
230 %%%%%%%%%%%%% Methods in alphabetic order %%%%%%%%%%%%%
231 \helponly{\insertatlevel{2}{
237 \membersection{wxCmdLineParser::wxCmdLineParser
}\label{wxcmdlineparserwxcmdlineparserdef
}
239 \func{}{wxCmdLineParser
}{\void}
241 Default constructor. You must use
242 \helpref{SetCmdLine
}{wxcmdlineparsersetcmdlineargc
} later.
244 \membersection{wxCmdLineParser::wxCmdLineParser
}\label{wxcmdlineparserwxcmdlineparserargc
}
246 \func{}{wxCmdLineParser
}{\param{int
}{argc
},
\param{char**
}{argv
}}
248 Constructor specifies the command line to parse. This is the traditional
249 (Unix) command line format. The parameters
{\it argc
} and
{\it argv
} have the
250 same meaning as for
{\tt main()
} function.
252 \membersection{wxCmdLineParser::wxCmdLineParser
}\label{wxcmdlineparserwxcmdlineparserstr
}
254 \func{}{wxCmdLineParser
}{\param{const wxString\&
}{cmdline
}}
256 Constructor specifies the command line to parse in Windows format. The parameter
257 {\it cmdline
} has the same meaning as the corresponding parameter of
260 \membersection{wxCmdLineParser::wxCmdLineParser
}\label{wxcmdlineparserwxcmdlineparserdesc
}
262 \func{}{wxCmdLineParser
}{\param{const wxCmdLineEntryDesc*
}{desc
}}
264 Same as
\helpref{wxCmdLineParser
}{wxcmdlineparserwxcmdlineparserdef
}, but also
265 specifies the
\helpref{command line description
}{wxcmdlineparsersetdesc
}.
267 \membersection{wxCmdLineParser::wxCmdLineParser
}\label{wxcmdlineparserwxcmdlineparserdescargc
}
269 \func{}{wxCmdLineParser
}{\param{const wxCmdLineEntryDesc*
}{desc
},
\param{int
}{argc
},
\param{char**
}{argv
}}
271 Same as
\helpref{wxCmdLineParser
}{wxcmdlineparserwxcmdlineparserargc
}, but also
272 specifies the
\helpref{command line description
}{wxcmdlineparsersetdesc
}.
274 \membersection{wxCmdLineParser::wxCmdLineParser
}\label{wxcmdlineparserwxcmdlineparserdescstr
}
276 \func{}{wxCmdLineParser
}{\param{const wxCmdLineEntryDesc*
}{desc
},
\param{const wxString\&
}{cmdline
}}
278 Same as
\helpref{wxCmdLineParser
}{wxcmdlineparserwxcmdlineparserstr
}, but also
279 specifies the
\helpref{command line description
}{wxcmdlineparsersetdesc
}.
281 \membersection{wxCmdLineParser::SetCmdLine
}\label{wxcmdlineparsersetcmdlineargc
}
283 \func{void
}{SetCmdLine
}{\param{int
}{argc
},
\param{char**
}{argv
}}
285 Set command line to parse after using one of the constructors which don't do it.
289 \helpref{wxCmdLineParser
}{wxcmdlineparserwxcmdlineparserargc
}
291 \membersection{wxCmdLineParser::SetCmdLine
}\label{wxcmdlineparsersetcmdlinestr
}
293 \func{void
}{SetCmdLine
}{\param{const wxString\&
}{cmdline
}}
295 Set command line to parse after using one of the constructors which don't do it.
299 \helpref{wxCmdLineParser
}{wxcmdlineparserwxcmdlineparserstr
}
301 \membersection{wxCmdLineParser::
\destruct{wxCmdLineParser
}}\label{wxcmdlineparserdtor
}
303 \func{}{\destruct{wxCmdLineParser
}}{\void}
305 Frees resources allocated by the object.
307 {\bf NB:
} destructor is not virtual, don't use this class polymorphically.
309 \membersection{wxCmdLineParser::SetSwitchChars
}\label{wxcmdlineparsersetswitchchars
}
311 \func{void
}{SetSwitchChars
}{\param{const wxString\&
}{switchChars
}}
313 {\it switchChars
} contains all characters with which an option or switch may
314 start. Default is
{\tt "-"
} for Unix,
{\tt "-/"
} for Windows.
316 \membersection{wxCmdLineParser::EnableLongOptions
}\label{wxcmdlineparserenablelongoptions
}
318 \func{void
}{EnableLongOptions
}{\param{bool
}{enable = TRUE
}}
320 Enable or disable support for the long options.
322 As long options are not (yet) POSIX-compliant, this option allows to disable
327 \helpref{Customization
}{wxcmdlineparsercustomization
}
329 \membersection{wxCmdLineParser::DisableLongOptions
}\label{wxcmdlineparserdisablelongoptions
}
331 \func{void
}{DisableLongOptions
}{\void}
333 Ientical to
\helpref{EnableLongOptions(FALSE)
}{wxcmdlineparserenablelongoptions
}.
335 \membersection{wxCmdLineParser::SetLogo
}\label{wxcmdlineparsersetlogo
}
337 \func{void
}{SetLogo
}{\param{const wxString\&
}{logo
}}
339 {\it logo
} is some extra text which will be shown by
340 \helpref{Usage
}{wxcmdlineparserusage
} method.
342 \membersection{wxCmdLineParser::SetDesc
}\label{wxcmdlineparsersetdesc
}
344 \func{void
}{SetDesc
}{\param{const wxCmdLineEntryDesc*
}{desc
}}
346 Construct the command line description
348 Take the command line description from the wxCMD
\_LINE\_NONE terminated table.
353 static const wxCmdLineEntryDesc cmdLineDesc
[] =
355 { wxCMD_LINE_SWITCH, "v", "verbose", "be verbose"
},
356 { wxCMD_LINE_SWITCH, "q", "quiet", "be quiet"
},
358 { wxCMD_LINE_OPTION, "o", "output", "output file"
},
359 { wxCMD_LINE_OPTION, "i", "input", "input dir"
},
360 { wxCMD_LINE_OPTION, "s", "size", "output block size", wxCMD_LINE_VAL_NUMBER
},
361 { wxCMD_LINE_OPTION, "d", "date", "output file date", wxCMD_LINE_VAL_DATE
},
363 { wxCMD_LINE_PARAM, NULL, NULL, "input file", wxCMD_LINE_VAL_STRING, wxCMD_LINE_PARAM_MULTIPLE
},
368 wxCmdLineParser parser;
370 parser.SetDesc(cmdLineDesc);
373 \membersection{wxCmdLineParser::AddSwitch
}\label{wxcmdlineparseraddswitch
}
375 \func{void
}{AddSwitch
}{\param{const wxString\&
}{name
},
\param{const wxString\&
}{lng = wxEmptyString
},
\param{const wxString\&
}{desc = wxEmptyString
},
\param{int
}{flags =
0}}
377 Add a switch
{\it name
} with an optional long name
{\it lng
} (no long name if it
378 is empty, which is default), description
{\it desc
} and flags
{\it flags
} to the
379 command line description.
381 \membersection{wxCmdLineParser::AddOption
}\label{wxcmdlineparseraddoption
}
383 \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}}
385 Add an option
{\it name
} with an optional long name
{\it lng
} (no long name if
386 it is empty, which is default) taking a value of the given type (string by
387 default) to the command line description.
389 \membersection{wxCmdLineParser::AddParam
}\label{wxcmdlineparseraddparam
}
391 \func{void
}{AddParam
}{\param{const wxString\&
}{desc = wxEmptyString
},
\param{wxCmdLineParamType
}{type = wxCMD
\_LINE\_VAL\_STRING},
\param{int
}{flags =
0}}
393 Add a parameter of the given
{\it type
} to the command line description.
395 \membersection{wxCmdLineParser::Parse
}\label{wxcmdlineparserparse
}
397 \func{int
}{Parse
}{\void}
399 Parse the command line, return $
0$ if ok, $-
1$ if
{\tt "-h"
} or
{\tt "--help"
}
400 option was encountered and the help message was given or a positive value if a
401 syntax error occured.
403 \membersection{wxCmdLineParser::Usage
}\label{wxcmdlineparserusage
}
405 \func{void
}{Usage
}{\void}
407 Give the standard usage message describing all program options. It will use the
408 options and parameters descriptions specified earlier, so the resulting message
409 will not be helpful to the user unless the descriptions were indeed specified.
413 \helpref{SetLogo
}{wxcmdlineparsersetlogo
}
415 \membersection{wxCmdLineParser::Found
}\label{wxcmdlineparserfoundswitch
}
417 \constfunc{bool
}{Found
}{\param{const wxString\&
}{name
}}
419 Returns TRUE if the given switch was found, FALSE otherwise.
421 \membersection{wxCmdLineParser::Found
}\label{wxcmdlineparserfoundstringoption
}
423 \constfunc{bool
}{Found
}{\param{const wxString\&
}{name
},
\param{wxString*
}{value
}}
425 Returns TRUE if an option taking a string value was found and stores the
426 value in the provided pointer (which should not be NULL).
428 \membersection{wxCmdLineParser::Found
}\label{wxcmdlineparserfoundintoption
}
430 \constfunc{bool
}{Found
}{\param{const wxString\&
}{name
},
\param{long*
}{value
}}
432 Returns TRUE if an option taking an integer value was found and stores
433 the value in the provided pointer (which should not be NULL).
435 \membersection{wxCmdLineParser::Found
}\label{wxcmdlineparserfounddateoption
}
437 \constfunc{bool
}{Found
}{\param{const wxString\&
}{name
},
\param{wxDateTime*
}{value
}}
439 Returns TRUE if an option taking a date value was found and stores the
440 value in the provided pointer (which should not be NULL).
442 \membersection{wxCmdLineParser::GetParamCount
}\label{wxcmdlineparsergetparamcount
}
444 \constfunc{size
\_t}{GetParamCount
}{\void}
446 Returns the number of parameters found. This function makes sense mostly if you
447 had used
{\tt wxCMD
\_LINE\_PARAM\_MULTIPLE} flag.
449 \membersection{wxCmdLineParser::GetParam
}\label{wxcmdlineparsergetparam
}
451 \constfunc{wxString
}{GetParam
}{\param{size
\_t }{n =
0u}}
453 Returns the value of Nth parameter (as string only for now).
457 \helpref{GetParamCount
}{wxcmdlineparsergetparamcount
}