added interface headers with latest discussed changes
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52381 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Francesco Montorsi
304
interface/cmdline.h
Normal file
304
interface/cmdline.h
Normal file
@@ -0,0 +1,304 @@
|
||||
/////////////////////////////////////////////////////////////////////////////
|
||||
// Name: cmdline.h
|
||||
// Purpose: documentation for wxCmdLineParser class
|
||||
// Author: wxWidgets team
|
||||
// RCS-ID: $Id$
|
||||
// Licence: wxWindows license
|
||||
/////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
/**
|
||||
@class wxCmdLineParser
|
||||
@wxheader{cmdline.h}
|
||||
|
||||
wxCmdLineParser is a class for parsing the command line.
|
||||
|
||||
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, ...).
|
||||
|
||||
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
|
||||
|
||||
In the documentation below the following terminology is used:
|
||||
|
||||
|
||||
|
||||
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".
|
||||
|
||||
|
||||
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 which allows
|
||||
to specify the name of the output file.
|
||||
|
||||
|
||||
parameter
|
||||
|
||||
|
||||
This is a required program argument.
|
||||
|
||||
|
||||
|
||||
@library{wxbase}
|
||||
@category{appmanagement}
|
||||
|
||||
@seealso
|
||||
wxApp::argc and wxApp::argv, console sample
|
||||
*/
|
||||
class wxCmdLineParser
|
||||
{
|
||||
public:
|
||||
//@{
|
||||
/**
|
||||
Specifies both the command line (in Windows format) and the
|
||||
@ref setdesc() "command line description".
|
||||
*/
|
||||
wxCmdLineParser();
|
||||
wxCmdLineParser(int argc, char** argv);
|
||||
wxCmdLineParser(int argc, wchar_t** argv);
|
||||
wxCmdLineParser(const wxString& cmdline);
|
||||
wxCmdLineParser(const wxCmdLineEntryDesc* desc);
|
||||
wxCmdLineParser(const wxCmdLineEntryDesc* desc, int argc,
|
||||
char** argv);
|
||||
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.
|
||||
*/
|
||||
~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.
|
||||
*/
|
||||
void AddOption(const wxString& name,
|
||||
const wxString& lng = wxEmptyString,
|
||||
const wxString& desc = wxEmptyString,
|
||||
wxCmdLineParamType type = wxCMD_LINE_VAL_STRING,
|
||||
int flags = 0);
|
||||
|
||||
/**
|
||||
Add a parameter of the given @e 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.
|
||||
*/
|
||||
void AddSwitch(const wxString& name,
|
||||
const wxString& lng = wxEmptyString,
|
||||
const wxString& desc = wxEmptyString,
|
||||
int flags = 0);
|
||||
|
||||
/**
|
||||
Returns @true if long options are enabled, otherwise @false.
|
||||
|
||||
@sa EnableLongOptions()
|
||||
*/
|
||||
bool AreLongOptionsEnabled();
|
||||
|
||||
/**
|
||||
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);
|
||||
|
||||
/**
|
||||
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.
|
||||
*/
|
||||
|
||||
|
||||
/**
|
||||
Identical to @ref enablelongoptions() EnableLongOptions(@false).
|
||||
*/
|
||||
void DisableLongOptions();
|
||||
|
||||
/**
|
||||
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()
|
||||
*/
|
||||
void EnableLongOptions(bool enable = @true);
|
||||
|
||||
//@{
|
||||
/**
|
||||
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);
|
||||
//@}
|
||||
|
||||
/**
|
||||
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();
|
||||
|
||||
/**
|
||||
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.
|
||||
*/
|
||||
|
||||
|
||||
/**
|
||||
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);
|
||||
|
||||
/**
|
||||
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.
|
||||
*/
|
||||
|
||||
|
||||
//@{
|
||||
/**
|
||||
Set 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);
|
||||
void SetCmdLine(const wxString& cmdline);
|
||||
//@}
|
||||
|
||||
/**
|
||||
Construct the command line description
|
||||
|
||||
Take the command line description from the wxCMD_LINE_NONE terminated table.
|
||||
|
||||
Example of usage:
|
||||
*/
|
||||
void SetDesc(const wxCmdLineEntryDesc* desc);
|
||||
|
||||
/**
|
||||
@e 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.
|
||||
*/
|
||||
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()
|
||||
*/
|
||||
void Usage();
|
||||
};
|
||||
Reference in New Issue
Block a user