// Purpose: interface of wxCmdLineParser
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
wxCmdLineEntryDesc::flags field is a combination of these bit masks.
Notice that by default (i.e. if flags are just 0), options are optional
- (sic) and each call to wxCmdLineEntryDesc::AddParam() allows one more
+ (sic) and each call to wxCmdLineParser::AddParam() allows one more
parameter - this may be changed by giving non-default flags to it, i.e. use
- wxCMD_LINE_OPTION_MANDATORY to require that the option is given and
- wxCMD_LINE_PARAM_OPTIONAL to make a parameter optional. Also,
- wxCMD_LINE_PARAM_MULTIPLE may be specified if the programs accepts a
+ @c wxCMD_LINE_OPTION_MANDATORY to require that the option is given and
+ @c wxCMD_LINE_PARAM_OPTIONAL to make a parameter optional.
+
+ Also, @c wxCMD_LINE_PARAM_MULTIPLE may be specified if the programs accepts a
variable number of parameters - but it only can be given for the last
parameter in the command line description. If you use this flag, you will
probably need to use wxCmdLineEntryDesc::GetParamCount() to retrieve the
number of parameters effectively specified after calling
wxCmdLineEntryDesc::Parse().
- wxCMD_LINE_NEEDS_SEPARATOR can be specified to require a separator (either
+ @c wxCMD_LINE_NEEDS_SEPARATOR can be specified to require a separator (either
a colon, an equal sign or white space) between the option name and its
value. By default, no separator is required.
+
+ @c wxCMD_LINE_SWITCH_NEGATABLE can be specified if you want to allow the
+ user to specify the switch in both normal form and in negated one (e.g.
+ /R-). You will need to use wxCmdLineParser::FoundSwitch() to distinguish
+ between the normal and negated forms of the switch. This flag is new since
+ wxWidgets 2.9.2.
*/
-enum
+enum wxCmdLineEntryFlags
{
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 a separator before the value.
+ wxCMD_LINE_NEEDS_SEPARATOR = 0x10, ///< Must have a separator before the value.
+ wxCMD_LINE_SWITCH_NEGATABLE = 0x20 ///< This switch can be negated (e.g. /S-)
};
/**
- The possible values of wxCmdLineEntryDesc::type which specifies the type of
+ The possible values of wxCmdLineEntryDesc::type which specify the type of
the value accepted by an option.
*/
enum wxCmdLineParamType
*/
enum wxCmdLineEntryType
{
+ /// A boolean argument of the program; e.g. @c -v to enable verbose mode.
wxCMD_LINE_SWITCH,
+
+ /// An argument with an associated value; e.g. @c "-o filename" to specify
+ /// an optional output filename.
wxCMD_LINE_OPTION,
+
+ /// A parameter: a required program argument.
wxCMD_LINE_PARAM,
+
+ /// Additional usage text. See wxCmdLineParser::AddUsageText.
wxCMD_LINE_USAGE_TEXT,
+
wxCMD_LINE_NONE ///< Use this to terminate the list.
};
/**
- The structure wxCmdLineEntryDesc is used to describe the one command line
+ The state of a switch as returned by wxCmdLineParser::FoundSwitch().
+
+ @since 2.9.2
+*/
+enum wxCmdLineSwitchState
+{
+ /// The switch was found in negated form, i.e. followed by a '-'.
+ wxCMD_SWITCH_OFF,
+
+ /// The switch was not found at all on the command line.
+ wxCMD_SWITCH_NOT_FOUND
+
+ /// The switch was found (and was not negated)
+ wxCMD_SWITCH_ON
+};
+
+
+/**
+ Flags determining wxCmdLineParser::ConvertStringToArgs() behaviour.
+ */
+enum wxCmdLineSplitType
+{
+ wxCMD_LINE_SPLIT_DOS,
+ wxCMD_LINE_SPLIT_UNIX
+};
+
+/**
+ The structure wxCmdLineEntryDesc is used to describe a command line
switch, option or parameter. An array of such structures should be passed
- to wxCmdLineParser::SetDesc(). Also, the meanings of parameters of the
- wxCmdLineParser::AddXXX() functions are the same as of the corresponding
- fields in this structure.
-
- The field @c shortName is the usual, short, name of the switch or the
- option. @c longName is the corresponding long name or empty if the option
- has no long name. Both of these fields are unused for the parameters. Both
- the short and long option names can contain only letters, digits and the
- underscores.
-
- @c description is used by the wxCmdLineEntryDesc::Usage() method to
- construct a help message explaining the syntax of the program.
+ to wxCmdLineParser::SetDesc().
+
+ Note that the meanings of parameters of the wxCmdLineParser::AddXXX() functions
+ are the same as of the corresponding fields in this structure.
*/
struct wxCmdLineEntryDesc
{
+ /**
+ The kind of this program argument.
+ See ::wxCmdLineEntryType for more info.
+ */
wxCmdLineEntryType kind;
+
+ /**
+ The usual, short, name of the switch or the option.
+
+ It may contain only letters, digits and the underscores.
+ This field is unused if <tt>kind == wxCMD_LINE_PARAM</tt>.
+ */
const char *shortName;
+
+ /**
+ The long name for this program argument (may be empty if the option
+ has no long name).
+
+ It may contain only letters, digits and the underscores.
+ This field is unused if <tt>kind == wxCMD_LINE_PARAM</tt>.
+ */
const char *longName;
+
+ /**
+ This description is used by the wxCmdLineParser::Usage() method to
+ construct a help message explaining the syntax of the program.
+ */
const char *description;
+
+ /**
+ The type associated with this option (ignored if <tt>kind != wxCMD_LINE_OPTION</tt>).
+ See ::wxCmdLineParamType for more info.
+ */
wxCmdLineParamType type;
+
+ /**
+ A combination of one or more ::wxCmdLineEntryFlags enum values.
+ */
int flags;
};
/**
@class wxCmdLineParser
- @wxheader{cmdline.h}
wxCmdLineParser is a class for parsing the command line.
-# Call Parse().
-# Use Found() to retrieve the results.
+ You can also use wxApp's default command line processing just overriding
+ wxAppConsole::OnInitCmdLine() and wxAppConsole::OnCmdLineParsed().
+
In the documentation below the following terminology is used:
- - @b switch: This is a boolean option which can be given or not, but which
- doesn't have any value. We use the word switch to distinguish
+ - @b switch: a boolean option which can be given or not, but which doesn't have
+ any value. We use the word @e switch to distinguish
such boolean options from more generic options like those
described below. For example, @c "-v" might be a switch
meaning "enable verbose mode".
- - @b option: Option for us here is something which comes with a value 0
- unlike a switch. For example, @c -o: @c filename might be an
+ - @b option: a switch with a value associated to it.
+ For example, @c "-o filename" might be an
option for specifying the name of the output file.
- - @b parameter: This is a required program argument.
- - @b text: This is a text which can be shown in usage information.
+ - @b parameter: a required program argument.
@section cmdlineparser_construction Construction
@library{wxbase}
@category{appmanagement}
- @see wxApp::argc, wxApp::argv, @ref page_samples_console "Console Sample"
+ @see wxApp::argc, wxApp::argv, @ref page_samples_console
*/
class wxCmdLineParser
{
*/
wxCmdLineParser();
- //@{
/**
Constructor which specifies the command line to parse. This is the
traditional (Unix) command line format. The parameters @a argc and
@a argv have the same meaning as the typical @c main() function.
- The second overloaded constructor is only available in Unicode build.
- The first one is available in both ANSI and Unicode modes because under
+ This constructor 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.
*/
wxCmdLineParser(int argc, char** argv);
+
+ /**
+ Constructor which specifies the command line to parse.
+ This is the traditional (Unix) command line format.
+
+ The parameters @a argc and @a argv have the same meaning as the typical
+ @c main() function.
+
+ This constructor is only available in Unicode build.
+ */
wxCmdLineParser(int argc, wchar_t** argv);
- //@}
/**
Constructor which specify the command line to parse in Windows format.
*/
~wxCmdLineParser();
+ /**
+ Adds an option with only long form.
+
+ This is just a convenient wrapper for AddOption() passing an empty
+ string as short option name.
+
+ @since 2.9.3
+ */
+ void AddLongOption(const wxString& lng,
+ const wxString& desc = wxEmptyString,
+ wxCmdLineParamType type = wxCMD_LINE_VAL_STRING,
+ int flags = 0);
+
+ /**
+ Adds a switch with only long form.
+
+ This is just a convenient wrapper for AddSwitch() passing an empty
+ string as short switch name.
+
+ @since 2.9.3
+ */
+
+ void AddLongSwitch(const wxString& lng,
+ const wxString& desc = wxEmptyString,
+ int flags = 0);
+
/**
Add an option @a name with an optional long name @a lng (no long name
if it is empty, which is default) taking a value of the given type
bool AreLongOptionsEnabled() const;
/**
- 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.
+ Breaks down the string containing the full command line in words.
+
+ Words are separated by whitespace and double quotes can be used to
+ preserve the spaces inside the words.
+
+ By default, this function uses Windows-like word splitting algorithm,
+ i.e. single quotes have no special meaning and backslash can't be used
+ to escape spaces neither. With @c wxCMD_LINE_SPLIT_UNIX flag Unix
+ semantics is used, i.e. both single and double quotes can be used and
+ backslash can be used to escape all the other special characters.
*/
- static wxArrayString ConvertStringToArgs(const wxChar cmdline);
+ static wxArrayString
+ ConvertStringToArgs(const wxString& cmdline,
+ wxCmdLineSplitType flags = wxCMD_LINE_SPLIT_DOS);
/**
Identical to EnableLongOptions(@false).
*/
bool Found(const wxString& name) const;
+ /**
+ Returns whether the switch was found on the command line and whether it
+ was negated.
+
+ This method can be used for any kind of switch but is especially useful
+ for switches that can be negated, i.e. were added with
+ wxCMD_LINE_SWITCH_NEGATABLE flag, as otherwise Found() is simpler to
+ use.
+
+ However Found() doesn't allow to distinguish between switch specified
+ normally, i.e. without dash following it, and negated switch, i.e. with
+ the following dash. This method will return @c wxCMD_SWITCH_ON or @c
+ wxCMD_SWITCH_OFF depending on whether the switch was negated or not.
+ And if the switch was not found at all, @c wxCMD_SWITCH_NOT_FOUND is
+ returned.
+
+ @since 2.9.2
+ */
+ wxCmdLineSwitchState FoundSwitch(const wxString& name) const;
+
/**
Returns true if an option taking a string value was found and stores
the value in the provided pointer (which should not be @NULL).
projects / wxWidgets.git / blobdiff