X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7c913512a4c9f36e11e07ea707002fab1608d324..7c0d297a1f761de31d3a4ac924fa2080b5bbaf41:/interface/cmdline.h diff --git a/interface/cmdline.h b/interface/cmdline.h index e5ab88761e..11d7b27d75 100644 --- a/interface/cmdline.h +++ b/interface/cmdline.h @@ -1,11 +1,89 @@ ///////////////////////////////////////////////////////////////////////////// // Name: cmdline.h -// Purpose: documentation for wxCmdLineParser class +// Purpose: interface of wxCmdLineParser // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// +/** + 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 + 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 + 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 + a colon, an equal sign or white space) between the option name and its + value. By default, no separator is required. +*/ +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 a separator before the value. +}; + +/** + The possible values of wxCmdLineEntryDesc::type which specifies the type of + the value accepted by an option. +*/ +enum wxCmdLineParamType +{ + wxCMD_LINE_VAL_STRING, + wxCMD_LINE_VAL_NUMBER, + wxCMD_LINE_VAL_DATE, + wxCMD_LINE_VAL_DOUBLE, + wxCMD_LINE_VAL_NONE +}; + +/** + The type of a command line entity used for wxCmdLineEntryDesc::kind. +*/ +enum wxCmdLineEntryType +{ + wxCMD_LINE_SWITCH, + wxCMD_LINE_OPTION, + wxCMD_LINE_PARAM, + wxCMD_LINE_NONE ///< Use this to terminate the list. +}; + +/** + The structure wxCmdLineEntryDesc is used to describe the one 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. +*/ +struct wxCmdLineEntryDesc +{ + wxCmdLineEntryType kind; + const char *shortName; + const char *longName; + const char *description; + wxCmdLineParamType type; + int flags; +}; + /** @class wxCmdLineParser @wxheader{cmdline.h} @@ -14,83 +92,176 @@ It has the following features: - distinguishes options, switches and parameters; allows option grouping - allows both short and long options - automatically generates the usage message from the command line description - does type checks on the options values (number, date, ...). + - distinguishes options, switches and parameters + - allows option grouping + - allows both short and long options + - automatically generates the usage message from the command line description + - checks types of the options values (number, date, ...). To use it you should follow these steps: - @ref wxCmdLineParser::construction construct an object of this class - giving it the command line to parse and optionally its description or use - @c AddXXX() functions later - call @c Parse() - use @c Found() to retrieve the results + -# @ref cmdlineparser_construction "Construct" an object of this class + giving it the command line to parse and optionally its description or + use the @c AddXXX() functions later. + -# Call Parse(). + -# Use Found() to retrieve the results. 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 + 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:filename might be an + option for specifing the name of the output file. + - @b parameter: This is a required program argument. + + @section cmdlineparser_construction Construction - switch + Before Parse() can be called, the command line parser object must have the + command line to parse and also the rules saying which switches, options and + parameters are valid - this is called command line description in what + follows. + You have complete freedom of choice as to when specify the required + information, the only restriction is that it must be done before calling + Parse(). - 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 such boolean - options from more generic options like those described below. For example, - @c -v might be a switch meaning "enable verbose mode". + To specify the command line to parse you may use either one of constructors + accepting it (wxCmdLineParser(int, char**) or + wxCmdLineParser(const wxString&) usually) or, if you use the default + constructor, you can do it later by calling SetCmdLine(). + The same holds for command line description: it can be specified either in + the constructor (with or without the command line itself) or constructed + later using either SetDesc() or combination of AddSwitch(), AddOption() and + AddParam() methods. - option + Using constructors or SetDesc() uses a (usually const static) table + containing the command line description. If you want to decide which + options to accept during the run-time, using one of the AddXXX() functions + above might be preferable. - Option for us here is something which comes with a value 0 - unlike a switch. For example, @c -o:filename might be an option which allows - to specify the name of the output file. + @section cmdlineparser_customization Customization + wxCmdLineParser has several global options which may be changed by the + application. All of the functions described in this section should be + called before Parse(). - parameter + 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 + abbreviations of them. As long options are used by more and more + applications, they are enabled by default, but may be disabled with + DisableLongOptions(). + Another global option is the set of characters which may be used to start + an option (otherwise, the word on the command line is assumed to be a + parameter). Under Unix, "-" is always used, but Windows has at least two + common choices for this: "-" and "/". Some programs also use "+". The + default is to use what suits most the current platform, but may be changed + with SetSwitchChars() method. - This is a required program argument. + Finally, SetLogo() can be used to show some application-specific text + before the explanation given by Usage() function. + @section cmdlineparser_parsing Parsing the Command Line + + After the command line description was constructed and the desired options + were set, you can finally call Parse() method. It returns 0 if the command + line was correct and was parsed, -1 if the help option was specified (this + is a separate case as, normally, the program will 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 wxWidgets logging + functions. + + + @section cmdlineparser_results Getting Results + + After calling Parse() (and if it returned 0), you may access the results of + parsing using one of overloaded Found() methods. + + For a simple switch, you will simply call Found to determine if the switch + was given or not, for an option or a parameter, you will call a version of + Found() which also returns the associated value in the provided variable. + All Found() functions return true if the switch or option were found in the + command line or false if they were not specified. + @library{wxbase} @category{appmanagement} - @seealso - wxApp::argc and wxApp::argv, console sample + @see wxApp::argc, wxApp::argv, @ref page_samples_console "Console Sample" */ class wxCmdLineParser { public: - //@{ /** - Specifies both the command line (in Windows format) and the - @ref setdesc() "command line description". + Default constructor, you must use SetCmdLine() later. */ 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 + some platforms the command line arguments are passed as ASCII strings + even to Unicode programs. + */ wxCmdLineParser(int argc, char** argv); wxCmdLineParser(int argc, wchar_t** argv); + //@} + + /** + Constructor which specify the command line to parse in Windows format. + The parameter cmdline has the same meaning as the corresponding + parameter of @c WinMain(). + */ wxCmdLineParser(const wxString& cmdline); + + /** + Specifies the @ref SetDesc() "command line description" but not the + command line. You must use SetCmdLine() later. + */ wxCmdLineParser(const wxCmdLineEntryDesc* desc); + + /** + Specifies both the command line (in Unix format) and the + @ref SetDesc() "command line description". + */ wxCmdLineParser(const wxCmdLineEntryDesc* desc, int argc, char** argv); + + /** + Specifies both the command line (in Windows format) and the + @ref SetDesc() "command line description". + */ wxCmdLineParser(const wxCmdLineEntryDesc* desc, const wxString& cmdline); - //@} /** Frees resources allocated by the object. - - @b NB: destructor is not virtual, don't use this class polymorphically. + + @note This destructor is not virtual, don't use this class + polymorphically. */ ~wxCmdLineParser(); /** - Add an option @e name with an optional long name @e 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. + 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 + (string by default) to the command line description. */ void AddOption(const wxString& name, const wxString& lng = wxEmptyString, @@ -99,16 +270,16 @@ public: int flags = 0); /** - Add a parameter of the given @e type to the command line description. + Add a parameter of the given @a type to the command line description. */ void AddParam(const wxString& desc = wxEmptyString, wxCmdLineParamType type = wxCMD_LINE_VAL_STRING, int flags = 0); /** - Add a switch @e name with an optional long name @e lng (no long name if it - is empty, which is default), description @e desc and flags @e flags to the - command line description. + Add a switch @a name with an optional long name @a lng (no long name if + it is empty, which is default), description @a desc and flags @a flags + to the command line description. */ void AddSwitch(const wxString& name, const wxString& lng = wxEmptyString, @@ -117,155 +288,92 @@ public: /** Returns @true if long options are enabled, otherwise @false. - - @sa EnableLongOptions() + + @see EnableLongOptions() */ - bool AreLongOptionsEnabled(); + bool AreLongOptionsEnabled() const; /** - Before Parse() can be called, the command line - parser object must have the command line to parse and also the rules saying - which switches, options and parameters are valid - this is called command line - description in what follows. - - You have complete freedom of choice as to when specify the required information, - the only restriction is that it must be done before calling - Parse(). - - To specify the command line to parse you may use either one of constructors - accepting it (@c wxCmdLineParser(argc, argv) or @c wxCmdLineParser(const - wxString) usually) - or, if you use the default constructor, you can do it later by calling - SetCmdLine(). - - The same holds for command line description: it can be specified either in - the @ref wxcmdlineparserctor() constructor (with or without - the command line itself) or constructed later using either - SetDesc() or combination of - AddSwitch(), - AddOption() and - AddParam() methods. - - Using constructors or SetDesc() uses a (usually - @c const static) table containing the command line description. If you want - to decide which options to accept during the run-time, using one of the - @c AddXXX() functions above might be preferable. + 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. */ + static wxArrayString ConvertStringToArgs(const wxChar cmdline); + /** + Identical to EnableLongOptions(@false). + */ + void DisableLongOptions(); /** - 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. + Enable or disable support for the long options. + + As long options are not (yet) POSIX-compliant, this option allows to + disable them. + + @see @ref cmdlineparser_customization and AreLongOptionsEnabled() */ - static wxArrayString ConvertStringToArgs(const wxChar cmdline); + void EnableLongOptions(bool enable = true); /** - wxCmdLineParser has several global options which may be changed by the - application. All of the functions described in this section should be called - before Parse(). - - 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 (@c "--") and look - like this: @c --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(). - - Another global option is the set of characters which may be used to start an - option (otherwise, the word on the command line is assumed to be a parameter). - Under Unix, @c '-' is always used, but Windows has at least two common - choices for this: @c '-' and @c '/'. Some programs also use @c '+'. - The default is to use what suits most the current platform, but may be changed - with SetSwitchChars() method. - - Finally, SetLogo() can be used to show some - application-specific text before the explanation given by - Usage() function. + Returns @true if the given switch was found, @false otherwise. */ + bool Found(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). + */ + bool Found(const wxString& name, wxString* value) const; /** - Identical to @ref enablelongoptions() EnableLongOptions(@false). + Returns @true if an option taking an integer value was found and stores + the value in the provided pointer (which should not be @NULL). */ - void DisableLongOptions(); + bool Found(const wxString& name, long* value) const; /** - Enable or disable support for the long options. - - As long options are not (yet) POSIX-compliant, this option allows to disable - them. - - @sa Customization() and AreLongOptionsEnabled() + Returns @true if an option taking a float value was found and stores + the value in the provided pointer (which should not be @NULL). */ - void EnableLongOptions(bool enable = @true); + bool Found(const wxString& name, double* value) const; - //@{ /** Returns @true if an option taking a date value was found and stores the value in the provided pointer (which should not be @NULL). */ - bool Found(const wxString& name); - bool Found(const wxString& name, wxString* value); - bool Found(const wxString& name, long* value); - bool Found(const wxString& name, wxDateTime* value); - //@} + bool Found(const wxString& name, wxDateTime* value) const; /** Returns the value of Nth parameter (as string only). */ - wxString GetParam(size_t n = 0u); - - /** - Returns the number of parameters found. This function makes sense mostly if you - had used @c wxCMD_LINE_PARAM_MULTIPLE flag. - */ - size_t GetParamCount(); + wxString GetParam(size_t n = 0) const; /** - After calling Parse() (and if it returned 0), - you may access the results of parsing using one of overloaded @c Found() - methods. - - For a simple switch, you will simply call - Found() to determine if the switch was given - or not, for an option or a parameter, you will call a version of @c Found() - which also returns the associated value in the provided variable. All - @c Found() functions return @true if the switch or option were found in the - command line or @false if they were not specified. + Returns the number of parameters found. This function makes sense + mostly if you had used @c wxCMD_LINE_PARAM_MULTIPLE flag. */ - + size_t GetParamCount() const; /** 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. - - @param giveUsage - If @true (default), the usage message is given if a - syntax error was encountered while parsing the command line or if help was - requested. If @false, only error messages about possible syntax errors - are given, use Usage to show the usage message - from the caller if needed. - */ - int Parse(bool giveUsage = @true); + option was encountered and the help message was given or a positive + value if a syntax error occurred. - /** - After the command line description was constructed and the desired options were - set, you can finally call Parse() method. - It returns 0 if the command line was correct and was parsed, -1 if the help - option was specified (this is a separate case as, normally, the program will - 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 wxWidgets logging functions. + @param giveUsage + If @true (default), the usage message is given if a syntax error + was encountered while parsing the command line or if help was + requested. If @false, only error messages about possible syntax + errors are given, use Usage to show the usage message from the + caller if needed. */ - + int Parse(bool giveUsage = true); //@{ /** - Set command line to parse after using one of the constructors which don't do it. + Set the command line to parse after using one of the constructors which + don't do it. */ void SetCmdLine(int argc, char** argv); void SetCmdLine(int argc, wchar_t** argv); @@ -273,32 +381,55 @@ public: //@} /** - Construct the command line description - - Take the command line description from the wxCMD_LINE_NONE terminated table. - + Constructs the command line description. + + Take the command line description from the wxCMD_LINE_NONE terminated + table. + Example of usage: + + @code + static const wxCmdLineEntryDesc cmdLineDesc[] = + { + { wxCMD_LINE_SWITCH, "v", "verbose", "be verbose" }, + { wxCMD_LINE_SWITCH, "q", "quiet", "be quiet" }, + + { wxCMD_LINE_OPTION, "o", "output", "output file" }, + { wxCMD_LINE_OPTION, "i", "input", "input dir" }, + { wxCMD_LINE_OPTION, "s", "size", "output block size", wxCMD_LINE_VAL_NUMBER }, + { wxCMD_LINE_OPTION, "d", "date", "output file date", wxCMD_LINE_VAL_DATE }, + + { wxCMD_LINE_PARAM, NULL, NULL, "input file", wxCMD_LINE_VAL_STRING, wxCMD_LINE_PARAM_MULTIPLE }, + + { wxCMD_LINE_NONE } + }; + + wxCmdLineParser parser; + + parser.SetDesc(cmdLineDesc); + @endcode */ void SetDesc(const wxCmdLineEntryDesc* desc); /** - @e logo is some extra text which will be shown by - Usage() method. + The @a logo is some extra text which will be shown by Usage() method. */ void SetLogo(const wxString& logo); /** - @e switchChars contains all characters with which an option or switch may - start. Default is @c "-" for Unix, @c "-/" for Windows. + @a switchChars contains all characters with which an option or switch + may start. Default is @c "-" for Unix, @c "-/" for Windows. */ void SetSwitchChars(const wxString& switchChars); /** - Give the standard usage message describing all program options. It will use the - options and parameters descriptions specified earlier, so the resulting message - will not be helpful to the user unless the descriptions were indeed specified. - - @sa SetLogo() + Give the standard usage message describing all program options. It will + use the options and parameters descriptions specified earlier, so the + resulting message will not be helpful to the user unless the + descriptions were indeed specified. + + @see SetLogo() */ - void Usage(); + void Usage() const; }; +