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: cmdlpars.tex 33428 2005-04-08 14:34:30Z MW $ 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 529