X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..1b7751aaa9a86d76a850b9267bc0c201e3cea30f:/interface/wx/cmdline.h

diff --git a/interface/wx/cmdline.h b/interface/wx/cmdline.h
index 2196edb66a..fdc0526c70 100644
--- a/interface/wx/cmdline.h
+++ b/interface/wx/cmdline.h
@@ -3,39 +3,47 @@
 // 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
@@ -52,42 +60,102 @@ 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.
 
@@ -107,18 +175,20 @@ struct wxCmdLineEntryDesc
     -# 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
@@ -156,7 +226,7 @@ struct wxCmdLineEntryDesc
 
     First global option is the support for long (also known as GNU-style)
     options. The long options are the ones which start with two dashes and look
-    like "--verbose", i.e. they generally are complete words and not some
+    like "\--verbose", i.e. they generally are complete words and not some
     abbreviations of them. As long options are used by more and more
     applications, they are enabled by default, but may be disabled with
     DisableLongOptions().
@@ -200,7 +270,7 @@ struct wxCmdLineEntryDesc
     @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
 {
@@ -210,20 +280,27 @@ public:
     */
     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.
@@ -259,6 +336,32 @@ public:
     */
     ~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
@@ -302,12 +405,20 @@ public:
     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).
@@ -329,6 +440,26 @@ public:
     */
     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).
@@ -365,7 +496,7 @@ public:
     size_t GetParamCount() const;
 
     /**
-        Parse the command line, return 0 if ok, -1 if @c "-h" or @c "--help"
+        Parse the command line, return 0 if ok, -1 if @c "-h" or @c "\--help"
         option was encountered and the help message was given or a positive
         value if a syntax error occurred.