X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/c57e060dc35e26d81cd091be409c12e7b406c5a0..ab9717339232a7a728dea666c59b73fd6ac78dd3:/docs/latex/wx/cmdlpars.tex?ds=sidebyside diff --git a/docs/latex/wx/cmdlpars.tex b/docs/latex/wx/cmdlpars.tex index 443c1bd4cb..e7ab669a51 100644 --- a/docs/latex/wx/cmdlpars.tex +++ b/docs/latex/wx/cmdlpars.tex @@ -11,7 +11,7 @@ \section{\class{wxCmdLineParser}}\label{wxcmdlineparser} -wxCmdLineParser is a class for parsing command line. +wxCmdLineParser is a class for parsing the command line. It has the following features: @@ -53,6 +53,10 @@ No base class +\wxheading{Library} + +\helpref{wxBase}{librarieslist} + \wxheading{Constants} The structure wxCmdLineEntryDesc is used to describe the one command @@ -80,10 +84,10 @@ the following constants: \begin{verbatim} enum wxCmdLineEntryType { - wxCMD\_LINE\_SWITCH, - wxCMD\_LINE\_OPTION, - wxCMD\_LINE\_PARAM, - wxCMD\_LINE\_NONE // use this to terminate the list + wxCMD_LINE_SWITCH, + wxCMD_LINE_OPTION, + wxCMD_LINE_PARAM, + wxCMD_LINE_NONE // use this to terminate the list } \end{verbatim} } @@ -103,10 +107,10 @@ by an option or parameter are: \begin{verbatim} enum wxCmdLineParamType { - wxCMD\_LINE\_VAL\_STRING, // default - wxCMD\_LINE\_VAL\_NUMBER, - wxCMD\_LINE\_VAL\_DATE, - wxCMD\_LINE\_VAL\_NONE + wxCMD_LINE_VAL_STRING, // default + wxCMD_LINE_VAL_NUMBER, + wxCMD_LINE_VAL_DATE, + wxCMD_LINE_VAL_NONE } \end{verbatim} } @@ -117,11 +121,11 @@ Finally, the {\tt flags} field is a combination of the following bit masks: \begin{verbatim} enum { - wxCMD\_LINE\_OPTION\_MANDATORY = 0x01, // this option must be given - wxCMD\_LINE\_PARAM\_OPTIONAL = 0x02, // the parameter may be omitted - wxCMD\_LINE\_PARAM\_MULTIPLE = 0x04, // the parameter may be repeated - wxCMD\_LINE\_OPTION\_HELP = 0x08, // this option is a help request - wxCMD\_LINE\_NEEDS\_SEPARATOR = 0x10, // must have sep before the value + wxCMD_LINE_OPTION_MANDATORY = 0x01, // this option must be given + wxCMD_LINE_PARAM_OPTIONAL = 0x02, // the parameter may be omitted + wxCMD_LINE_PARAM_MULTIPLE = 0x04, // the parameter may be repeated + wxCMD_LINE_OPTION_HELP = 0x08, // this option is a help request + wxCMD_LINE_NEEDS_SEPARATOR = 0x10, // must have sep before the value } \end{verbatim} } @@ -150,6 +154,7 @@ console sample %%%%%%%%%%%%% Methods by group %%%%%%%%%%%%% \latexignore{\rtfignore{\wxheading{Function groups}}} + \membersection{Construction}\label{wxcmdlineparserconstruction} Before \helpref{Parse}{wxcmdlineparserparse} can be called, the command line @@ -162,15 +167,13 @@ the only restriction is that it must be done before calling \helpref{Parse}{wxcmdlineparserparse}. To specify the command line to parse you may use either one of constructors -accepting it (\helpref{wxCmdLineParser(argc, argv)}{wxcmdlineparserwxcmdlineparserargc} or -\helpref{wxCmdLineParser}{wxcmdlineparserwxcmdlineparserdescargc} usually) or, -if you use \helpref{the default constructor}{wxcmdlineparserwxcmdlineparserdef}, -you can do it later by calling -\helpref{SetCmdLine}{wxcmdlineparsersetcmdlineargc}. +accepting it (\tt{wxCmdLineParser(argc, argv)} or \tt{wxCmdLineParser(const wxString&)} usually) +or, if you use the default constructor, you can do it later by calling +\helpref{SetCmdLine}{wxcmdlineparsersetcmdline}. The same holds for command line description: it can be specified either in -the constructor (\helpref{without command line}{wxcmdlineparserwxcmdlineparserdesc} or -\helpref{together with it}{wxcmdlineparserwxcmdlineparserdescargc}) or +the constructor (\helpref{without\ command\ line}{wxcmdlineparserwxcmdlineparser} or +\helpref{together\ with\ it}{wxcmdlineparserwxcmdlineparserdescargc}) or constructed later using either \helpref{SetDesc}{wxcmdlineparsersetdesc} or combination of \helpref{AddSwitch}{wxcmdlineparseraddswitch}, \helpref{AddOption}{wxcmdlineparseraddoption} and @@ -178,9 +181,10 @@ combination of \helpref{AddSwitch}{wxcmdlineparseraddswitch}, Using constructors or \helpref{SetDesc}{wxcmdlineparsersetdesc} uses a (usually {\tt const static}) table containing the command line description. If you want -to decide which options to acccept during the run-time, using one of the +to decide which options to accept during the run-time, using one of the {\tt AddXXX()} functions above might be preferable. + \membersection{Customization}\label{wxcmdlineparsercustomization} wxCmdLineParser has several global options which may be changed by the @@ -205,6 +209,7 @@ Finally, \helpref{SetLogo}{wxcmdlineparsersetlogo} can be used to show some application-specific text before the explanation given by \helpref{Usage}{wxcmdlineparserusage} function. + \membersection{Parsing command line}\label{wxcmdlineparserparsing} After the command line description was constructed and the desired options were @@ -215,7 +220,8 @@ terminate after this) or a positive number if there was an error during the command line parsing. In the latter case, the appropriate error message and usage information are -logged by wxCmdLineParser itself using the standard wxWindows logging functions. +logged by wxCmdLineParser itself using the standard wxWidgets logging functions. + \membersection{Getting results}\label{wxcmdlineparsergettingresults} @@ -224,11 +230,11 @@ you may access the results of parsing using one of overloaded {\tt Found()} methods. For a simple switch, you will simply call -\helpref{Found}{wxcmdlineparserfoundswitch} to determine if the switch was given +\helpref{Found}{wxcmdlineparserfound} to determine if the switch was given or not, for an option or a parameter, you will call a version of {\tt Found()} which also returns the associated value in the provided variable. All -{\tt Found()} functions return TRUE if the switch or option were found in the -command line or FALSE if they were not specified. +{\tt Found()} functions return true if the switch or option were found in the +command line or false if they were not specified. %%%%%%%%%%%%% Methods in alphabetic order %%%%%%%%%%%%% \helponly{\insertatlevel{2}{ @@ -237,69 +243,73 @@ command line or FALSE if they were not specified. }} -\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparserdef} + +\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparser} \func{}{wxCmdLineParser}{\void} Default constructor. You must use -\helpref{SetCmdLine}{wxcmdlineparsersetcmdlineargc} later. +\helpref{SetCmdLine}{wxcmdlineparsersetcmdline} later. -\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparserargc} +\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparserdescargc} \func{}{wxCmdLineParser}{\param{int }{argc}, \param{char** }{argv}} -Constructor specifies the command line to parse. This is the traditional +\func{}{wxCmdLineParser}{\param{int }{argc}, \param{wchar\_t** }{argv}} + +Constructors which specify the command line to parse. This is the traditional (Unix) command line format. The parameters {\it argc} and {\it argv} have the same meaning as for {\tt main()} function. -\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparserstr} +The second overloaded constructor is only available in Unicode build. The +first one is available in both ANSI and Unicode modes because under some +platforms the command line arguments are passed as ASCII strings even to +Unicode programs. \func{}{wxCmdLineParser}{\param{const wxString\& }{cmdline}} -Constructor specifies the command line to parse in Windows format. The parameter +Constructor which specify the command line to parse in Windows format. The parameter {\it cmdline} has the same meaning as the corresponding parameter of {\tt WinMain()}. -\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparserdesc} - \func{}{wxCmdLineParser}{\param{const wxCmdLineEntryDesc* }{desc}} -Same as \helpref{wxCmdLineParser}{wxcmdlineparserwxcmdlineparserdef}, but also -specifies the \helpref{command line description}{wxcmdlineparsersetdesc}. - -\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparserdescargc} +Specifies the \helpref{command line description}{wxcmdlineparsersetdesc} but not the +command line. You must use \helpref{SetCmdLine}{wxcmdlineparsersetcmdline} later. \func{}{wxCmdLineParser}{\param{const wxCmdLineEntryDesc* }{desc}, \param{int }{argc}, \param{char** }{argv}} -Same as \helpref{wxCmdLineParser}{wxcmdlineparserwxcmdlineparserargc}, but also -specifies the \helpref{command line description}{wxcmdlineparsersetdesc}. - -\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparserdescstr} +Specifies both the command line (in Unix format) and the +\helpref{command line description}{wxcmdlineparsersetdesc}. \func{}{wxCmdLineParser}{\param{const wxCmdLineEntryDesc* }{desc}, \param{const wxString\& }{cmdline}} -Same as \helpref{wxCmdLineParser}{wxcmdlineparserwxcmdlineparserstr}, but also -specifies the \helpref{command line description}{wxcmdlineparsersetdesc}. +Specifies both the command line (in Windows format) and the +\helpref{command line description}{wxcmdlineparsersetdesc}. -\membersection{wxCmdLineParser::SetCmdLine}\label{wxcmdlineparsersetcmdlineargc} +\membersection{wxCmdLineParser::ConvertStringToArgs}\label{wxcmdlineparserconvertstringtoargs} -\func{void}{SetCmdLine}{\param{int }{argc}, \param{char** }{argv}} +\func{static wxArrayString}{ConvertStringToArgs}{\param{const wxChar }{*cmdline}} -Set command line to parse after using one of the constructors which don't do it. +Breaks down the string containing the full command line in words. The words are +separated by whitespace. The quotes can be used in the input string to quote +the white space and the back slashes can be used to quote the quotes. -\wxheading{See also} -\helpref{wxCmdLineParser}{wxcmdlineparserwxcmdlineparserargc} +\membersection{wxCmdLineParser::SetCmdLine}\label{wxcmdlineparsersetcmdline} + +\func{void}{SetCmdLine}{\param{int }{argc}, \param{char** }{argv}} -\membersection{wxCmdLineParser::SetCmdLine}\label{wxcmdlineparsersetcmdlinestr} +\func{void}{SetCmdLine}{\param{int }{argc}, \param{wchar\_t** }{argv}} + +Set command line to parse after using one of the constructors which don't do it. +The second overload of this function is only available in Unicode build. \func{void}{SetCmdLine}{\param{const wxString\& }{cmdline}} Set command line to parse after using one of the constructors which don't do it. -\wxheading{See also} -\helpref{wxCmdLineParser}{wxcmdlineparserwxcmdlineparserstr} \membersection{wxCmdLineParser::\destruct{wxCmdLineParser}}\label{wxcmdlineparserdtor} @@ -309,6 +319,7 @@ Frees resources allocated by the object. {\bf NB:} destructor is not virtual, don't use this class polymorphically. + \membersection{wxCmdLineParser::SetSwitchChars}\label{wxcmdlineparsersetswitchchars} \func{void}{SetSwitchChars}{\param{const wxString\& }{switchChars}} @@ -316,9 +327,10 @@ Frees resources allocated by the object. {\it switchChars} contains all characters with which an option or switch may start. Default is {\tt "-"} for Unix, {\tt "-/"} for Windows. + \membersection{wxCmdLineParser::EnableLongOptions}\label{wxcmdlineparserenablelongoptions} -\func{void}{EnableLongOptions}{\param{bool }{enable = TRUE}} +\func{void}{EnableLongOptions}{\param{bool }{enable = true}} Enable or disable support for the long options. @@ -327,13 +339,26 @@ them. \wxheading{See also} -\helpref{Customization}{wxcmdlineparsercustomization} +\helpref{Customization}{wxcmdlineparsercustomization} and \helpref{AreLongOptionsEnabled}{wxcmdlineparserarelongoptionsenabled} + \membersection{wxCmdLineParser::DisableLongOptions}\label{wxcmdlineparserdisablelongoptions} \func{void}{DisableLongOptions}{\void} -Ientical to \helpref{EnableLongOptions(FALSE)}{wxcmdlineparserenablelongoptions}. +Identical to \helpref{EnableLongOptions(false)}{wxcmdlineparserenablelongoptions}. + + +\membersection{wxCmdLineParser::AreLongOptionsEnabled}\label{wxcmdlineparserarelongoptionsenabled} + +\func{bool}{AreLongOptionsEnabled}{\void} + +Returns true if long options are enabled, otherwise false. + +\wxheading{See also} + +\helpref{EnableLongOptions}{wxcmdlineparserenablelongoptions} + \membersection{wxCmdLineParser::SetLogo}\label{wxcmdlineparsersetlogo} @@ -342,6 +367,7 @@ Ientical to \helpref{EnableLongOptions(FALSE)}{wxcmdlineparserenablelongoptions} {\it logo} is some extra text which will be shown by \helpref{Usage}{wxcmdlineparserusage} method. + \membersection{wxCmdLineParser::SetDesc}\label{wxcmdlineparsersetdesc} \func{void}{SetDesc}{\param{const wxCmdLineEntryDesc* }{desc}} @@ -373,6 +399,7 @@ wxCmdLineParser parser; parser.SetDesc(cmdLineDesc); \end{verbatim} + \membersection{wxCmdLineParser::AddSwitch}\label{wxcmdlineparseraddswitch} \func{void}{AddSwitch}{\param{const wxString\& }{name}, \param{const wxString\& }{lng = wxEmptyString}, \param{const wxString\& }{desc = wxEmptyString}, \param{int }{flags = 0}} @@ -381,6 +408,7 @@ Add a switch {\it name} with an optional long name {\it lng} (no long name if it is empty, which is default), description {\it desc} and flags {\it flags} to the command line description. + \membersection{wxCmdLineParser::AddOption}\label{wxcmdlineparseraddoption} \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}} @@ -389,19 +417,30 @@ Add an option {\it name} with an optional long name {\it lng} (no long name if it is empty, which is default) taking a value of the given type (string by default) to the command line description. + \membersection{wxCmdLineParser::AddParam}\label{wxcmdlineparseraddparam} \func{void}{AddParam}{\param{const wxString\& }{desc = wxEmptyString}, \param{wxCmdLineParamType }{type = wxCMD\_LINE\_VAL\_STRING}, \param{int }{flags = 0}} Add a parameter of the given {\it type} to the command line description. + \membersection{wxCmdLineParser::Parse}\label{wxcmdlineparserparse} -\func{int}{Parse}{\void} +\func{int}{Parse}{\param{bool }{giveUsage = {\tt true}}} Parse the command line, return $0$ if ok, $-1$ if {\tt "-h"} or {\tt "--help"} option was encountered and the help message was given or a positive value if a -syntax error occured. +syntax error occurred. + +\wxheading{Parameters} + +\docparam{giveUsage}{If {\tt true} (default), the usage message is given if a +syntax error was encountered while parsing the command line or if help was +requested. If {\tt false}, only error messages about possible syntax errors +are given, use \helpref{Usage}{wxcmdlineparserusage} to show the usage message +from the caller if needed.} + \membersection{wxCmdLineParser::Usage}\label{wxcmdlineparserusage} @@ -415,33 +454,29 @@ will not be helpful to the user unless the descriptions were indeed specified. \helpref{SetLogo}{wxcmdlineparsersetlogo} -\membersection{wxCmdLineParser::Found}\label{wxcmdlineparserfoundswitch} -\constfunc{bool}{Found}{\param{const wxString\& }{name}} +\membersection{wxCmdLineParser::Found}\label{wxcmdlineparserfound} -Returns TRUE if the given switch was found, FALSE otherwise. +\constfunc{bool}{Found}{\param{const wxString\& }{name}} -\membersection{wxCmdLineParser::Found}\label{wxcmdlineparserfoundstringoption} +Returns \true if the given switch was found, false otherwise. \constfunc{bool}{Found}{\param{const wxString\& }{name}, \param{wxString* }{value}} -Returns TRUE if an option taking a string value was found and stores the +Returns \true if an option taking a string value was found and stores the value in the provided pointer (which should not be NULL). -\membersection{wxCmdLineParser::Found}\label{wxcmdlineparserfoundintoption} - \constfunc{bool}{Found}{\param{const wxString\& }{name}, \param{long* }{value}} -Returns TRUE if an option taking an integer value was found and stores +Returns \true if an option taking an integer value was found and stores the value in the provided pointer (which should not be NULL). -\membersection{wxCmdLineParser::Found}\label{wxcmdlineparserfounddateoption} - \constfunc{bool}{Found}{\param{const wxString\& }{name}, \param{wxDateTime* }{value}} -Returns TRUE if an option taking a date value was found and stores the +Returns \true if an option taking a date value was found and stores the value in the provided pointer (which should not be NULL). + \membersection{wxCmdLineParser::GetParamCount}\label{wxcmdlineparsergetparamcount} \constfunc{size\_t}{GetParamCount}{\void} @@ -449,11 +484,12 @@ value in the provided pointer (which should not be NULL). Returns the number of parameters found. This function makes sense mostly if you had used {\tt wxCMD\_LINE\_PARAM\_MULTIPLE} flag. + \membersection{wxCmdLineParser::GetParam}\label{wxcmdlineparsergetparam} \constfunc{wxString}{GetParam}{\param{size\_t }{n = 0u}} -Returns the value of Nth parameter (as string only for now). +Returns the value of Nth parameter (as string only). \wxheading{See also}