undo the last change as it results in buildbot configuration error

[wxWidgets.git] / interface / wx / cmdline.h

diff --git a/interface/wx/cmdline.h b/interface/wx/cmdline.h
index 5aae4a95b705b2055b9b7080f84d148319b1ec9c..affe5ebeda994d744a2debaabfc843112c6d9555 100644 (file)
--- a/interface/wx/cmdline.h
+++ b/interface/wx/cmdline.h
@@ -10,22 +10,23 @@
     wxCmdLineEntryDesc::flags field is a combination of these bit masks.
 
     Notice that by default (i.e. if flags are just 0), options are optional
     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
     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().
 
     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.
 */
     a colon, an equal sign or white space) between the option name and its
     value. By default, no separator is required.
 */

-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_OPTION_MANDATORY = 0x01, ///< This option must be given.
     wxCMD_LINE_PARAM_OPTIONAL   = 0x02, ///< The parameter may be omitted.


@@ -35,7 +36,7 @@ enum
 };
 
 /**
 };
 
 /**

-    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
     the value accepted by an option.
 */
 enum wxCmdLineParamType


@@ -52,36 +53,79 @@ enum wxCmdLineParamType
 */
 enum wxCmdLineEntryType
 {
 */
 enum wxCmdLineEntryType
 {

+    /// A boolean argument of the program; e.g. @c -v to enable verbose mode.

     wxCMD_LINE_SWITCH,
     wxCMD_LINE_SWITCH,

+    
+    /// An argument with an associated value; e.g. @c "-o filename" to specify
+    /// an optional output filename.

     wxCMD_LINE_OPTION,
     wxCMD_LINE_OPTION,

+    
+    /// A parameter: a required program argument.

     wxCMD_LINE_PARAM,
     wxCMD_LINE_PARAM,

+    
+    /// Additional usage text. See wxCmdLineParser::AddUsageText.

     wxCMD_LINE_USAGE_TEXT,
     wxCMD_LINE_USAGE_TEXT,

+    

     wxCMD_LINE_NONE     ///< Use this to terminate the list.
 };
 
 /**
     wxCMD_LINE_NONE     ///< Use this to terminate the list.
 };
 
 /**

-    The structure wxCmdLineEntryDesc is used to describe the one command line
+    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
     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
 {
 */
 struct wxCmdLineEntryDesc
 {

+    /**
+        The kind of this program argument.
+        See ::wxCmdLineEntryType for more info.
+    */

     wxCmdLineEntryType kind;
     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;
     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;
     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;
     const char *description;

+
+    /**
+        The type associated with this option (ignored if <tt>kind != wxCMD_LINE_OPTION</tt>).
+        See ::wxCmdLineParamType for more info.
+    */

     wxCmdLineParamType type;
     wxCmdLineParamType type;

+    
+    /**
+        A combination of one or more ::wxCmdLineEntryFlags enum values.
+    */

     int flags;
 };
 
     int flags;
 };
 


@@ -106,18 +150,20 @@ struct wxCmdLineEntryDesc
     -# Call Parse().
     -# Use Found() to retrieve the results.
 
     -# 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:
 
     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".
                  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.
                  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
 
 
     @section cmdlineparser_construction Construction


@@ -199,7 +245,7 @@ struct wxCmdLineEntryDesc
     @library{wxbase}
     @category{appmanagement}
 
     @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
 {
 */
 class wxCmdLineParser
 {


@@ -209,20 +255,27 @@ public:
     */
     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.
 
     /**
         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);
         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);
     wxCmdLineParser(int argc, wchar_t** argv);

-    //@}

 
     /**
         Constructor which specify the command line to parse in Windows format.
 
     /**
         Constructor which specify the command line to parse in Windows format.


@@ -301,12 +354,20 @@ public:
     bool AreLongOptionsEnabled() const;
 
     /**
     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).
 
     /**
         Identical to EnableLongOptions(@false).