%% Created: 27.03.00
%% RCS-ID: $Id$
%% Copyright: (c) Vadim Zeitlin
-%% License: wxWidgets license
+%% License: wxWindows license
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\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:
%%%%%%%%%%%%% Methods by group %%%%%%%%%%%%%
\latexignore{\rtfignore{\wxheading{Function groups}}}
+
\membersection{Construction}\label{wxcmdlineparserconstruction}
Before \helpref{Parse}{wxcmdlineparserparse} can be called, the command line
\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
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
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
In the latter case, the appropriate error message and usage information are
logged by wxCmdLineParser itself using the standard wxWidgets logging functions.
+
\membersection{Getting results}\label{wxcmdlineparsergettingresults}
After calling \helpref{Parse}{wxcmdlineparserparse} (and if it returned $0$),
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
}}
-\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::ConvertStringToArgs}\label{wxcmdlineparserconvertstringtoargs}
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.
-\membersection{wxCmdLineParser::SetCmdLine}\label{wxcmdlineparsersetcmdlineargc}
-\func{void}{SetCmdLine}{\param{int }{argc}, \param{char** }{argv}}
-
-Set command line to parse after using one of the constructors which don't do it.
+\membersection{wxCmdLineParser::SetCmdLine}\label{wxcmdlineparsersetcmdline}
-\wxheading{See also}
+\func{void}{SetCmdLine}{\param{int }{argc}, \param{char** }{argv}}
-\helpref{wxCmdLineParser}{wxcmdlineparserwxcmdlineparserargc}
+\func{void}{SetCmdLine}{\param{int }{argc}, \param{wchar\_t** }{argv}}
-\membersection{wxCmdLineParser::SetCmdLine}\label{wxcmdlineparsersetcmdlinestr}
+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}
{\bf NB:} destructor is not virtual, don't use this class polymorphically.
+
\membersection{wxCmdLineParser::SetSwitchChars}\label{wxcmdlineparsersetswitchchars}
\func{void}{SetSwitchChars}{\param{const wxString\& }{switchChars}}
{\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}}
\helpref{Customization}{wxcmdlineparsercustomization} and \helpref{AreLongOptionsEnabled}{wxcmdlineparserarelongoptionsenabled}
+
\membersection{wxCmdLineParser::DisableLongOptions}\label{wxcmdlineparserdisablelongoptions}
\func{void}{DisableLongOptions}{\void}
Identical to \helpref{EnableLongOptions(false)}{wxcmdlineparserenablelongoptions}.
+
\membersection{wxCmdLineParser::AreLongOptionsEnabled}\label{wxcmdlineparserarelongoptionsenabled}
\func{bool}{AreLongOptionsEnabled}{\void}
\helpref{EnableLongOptions}{wxcmdlineparserenablelongoptions}
+
\membersection{wxCmdLineParser::SetLogo}\label{wxcmdlineparsersetlogo}
\func{void}{SetLogo}{\param{const wxString\& }{logo}}
{\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}}
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}}
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}}
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}{\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}
are given, use \helpref{Usage}{wxcmdlineparserusage} to show the usage message
from the caller if needed.}
+
\membersection{wxCmdLineParser::Usage}\label{wxcmdlineparserusage}
\func{void}{Usage}{\void}
\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}
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}
projects / wxWidgets.git / blobdiff