|
|
Simple access to the command-line arguments.
It takes into account Qt-specific options, KDE-specific options and application specific options.
This class is used in main() via the static method init().
A typical KDE application should look like this:
int main(int argc, char *argv[]) { // Initialize command line args KCmdLineArgs::init(argc, argv, appName, description, version); // Tell which options are supported KCmdLineArgs::addCmdLineOptions( options ); // Add options from other components KUniqueApplication::addCmdLineOptions(); .... // Create application object without passing 'argc' and 'argv' again. KUniqueApplication app; .... // Handle our own options/argments // A KApplication will usually do this in main but this is not // necassery. // A KUniqueApplication might want to handle it in newInstance(). KCmdLineArgs *args = KCmdLineArgs::parsedArgs(); // A binary option (on / off) if (args->isSet("some-option")) .... // An option which takes an additional argument QCString anotherOptionArg = args->getOption("another-option"); // Arguments (e.g. files to open) for(int i = 0; i < args->count(); i++) // Counting start at 0! { // don't forget to convert to Unicode! openFile( QFile::decodeName( args->arg(i))); // Or more convenient: // openURL( args->url(i)); } args->clear(); // Free up some memory. .... }
options are defined as follow
static KCmdLineOptions options[] = { { "a", I18N_NOOP("A short binary option."), 0 }, { "b <file>", I18N_NOOP("A short option which takes an argument."), 0 }, { "c <speed>", I18N_NOOP("As above but with a default value."), "9600" }, { "option1", I18N_NOOP("A long binary option, off by default."), 0 }, { "nooption2", I18N_NOOP("A long binary option, on by default."), 0 }, { "option3 <file>", I18N_NOOP("A long option which takes an argument."), 0 }, { "option3 <speed>", I18N_NOOP("As above with 9600 as default."), "9600" }, { "d", 0, 0 }, { "option4", I18N_NOOP("A long option which has a short option as alias."), 0 }, { "e", 0, 0 }, { "nooption5", I18N_NOOP("Another long option with an alias."), 0 }, { "f", 0, 0 }, { "option6 <speed>", I18N_NOOP("'--option6 speed' is same a '-f speed'"), 0 }, { "+file", I18N_NOOP("A required argument 'file'.), 0 }, { "+[arg1]", I18N_NOOP("An optional argument 'arg1'."), 0 }, { 0, 0, 0 } // End of options. }
The I18N_NOOP macro is used to indicate that these strings should be marked for translation. The actual translation is done by KCmdLineArgs. You can't use i18n() here because we are setting up a static data structure and can't do translations at compile time.
Note that a program should define the options before any arguments.
When a long option has a short option as alias. A program should only check for the long option.
With the above options a command line could look like:
myapp -a -c 4800 --display localhost:0.0 --nooption5 -d /tmp/file
Long binary options can be in the form 'option' and 'nooption'. A command line may contain the same binary option multiple times, the last option determines the outcome:
myapp --nooption4 --option4 --nooption4
is the same as:
myapp --nooption4
void init (int _argc, char **_argv, const char *_appname, const char *_description, const char *_version, bool noKApp = false) |
Initialize class.
This function should be called as the very first thing in your application.
Parameters:
argc | As passed to main (...).
|
argv | As passed to main (...).
|
appname | The untranslated name of your application. This should
match with argv [0].
|
description | A short description of what your application is about. |
version | A version. |
noKApp | Don't add commandline options for QApplication/KApplication |
void init (int _argc, char **_argv, const KAboutData *about, bool noKApp = false) |
Initialize class.
This function should be called as the very first thing in your application.
Parameters:
argc | As passed to main (...).
|
argv | As passed to main (...).
|
about | A KAboutData object describing your program. |
noKApp | Don't add commandline options for QApplication / KApplication |
void addCmdLineOptions ( const KCmdLineOptions *options, const char *name=0, const char *id = 0, const char *afterId=0) |
Add options to your application.
You must make sure that all possible options have been added before any class uses the command line arguments.
The list of options should look like this:
static KCmdLineOptions options[] = { { "option1 <argument>", I18N_NOOP("Description 1"), "default" }, { "o", 0, 0 }, { "option2", I18N_NOOP("Description 2"), 0 }, { "nooption3", I18N_NOOP("Description 3"), 0 }, { 0, 0, 0} }
In BNF: cmd = myapp [options] file options = (option)* option = --option1 <argument> | (-o | --option2 | --nooption2) | ( --option3 | --nooption3 )
Instead of "--option3" one may also use "-option3"
Usage examples:
Parameters:
options | A list of options which your code supplies. |
id | A name with which these options can be identified. |
afterId | The options are inserted after this set of options. |
KCmdLineArgs * parsedArgs (const char *id=0) |
Access parsed arguments.
This function returns all command line arguments which your code handles. If unknown command line arguments are encountered the program is aborted and usage information is shown.
Parameters:
id | The name of the options you are interested in. |
QString cwd () |
Get the CWD (Current Working Directory) associated with the current command line arguments.
Typically this is needed in KUniqueApplication::newInstance() since the CWD of the process may be different from the CWD where the user started a second instance.
void usage (const char *id = 0) |
Print the usage help to @ds stdout and exit.
Parameters:
complete | If true, print all available options. |
void usage (const QString &error) |
Print an error to @ds stderr and the usage help to @ds stdout and exit.
void enable_i18n () |
Enable i18n to be able to print a translated error message.
N.B.: This function leaks memory so you are expected to exit afterwards, e.g. by calling usage().
QCString getOption (const char *option) |
Read out a string option.
Parameters:
option | The name of the option without '-'. |
Returns: The value of the option. If the option was not present on the command line the default is returned.
bool isSet (const char *option) |
Read out a boolean option or check for the presence of string option.
If the option is listed as '<option> <arg>'
this function returns true
if the option was present
and false
otherwise.
Parameters:
option | The name of the option without '-' or '-no'. |
Returns: The value of the option. If the option was not present on the cmdline the default is returned. If the option is listed as 'no<option>' the default is true. If the option is listed as '<option>' the default is false.
int count () |
Read the number of arguments that aren't options (but e.g. filenames).
Returns: the number of arguments that aren't options
const char * arg (int n) |
Read out an argument.
Parameters:
n | The argument to read. 0 is the first argument. count()-1 is the last argument. |
Returns: a const
char
@p * pointer to the n'th argument.
KURL url (int n) |
Read out an argument representing a URL.
The argument can be
Parameters:
n | The argument to read. 0 is the first argument. count()-1 is the last argument. |
Returns: a URL
representing the n'th argument.
void clear () |
Clear all options and arguments.
KCmdLineArgs ( const KCmdLineOptions *_options, const char *_id, const char *_name) |
Constructor.
~KCmdLineArgs () |
Use clear() if you want to free up some memory.
Destructor.
void findOption (const char *_opt, QCString opt, int &i, bool enabled) |
Checks what to do with a single option
void parseAllArgs () |
Parse all arguments, verify correct syntax and put all arguments where they belong.
int * qt_argc () |
Return argc
char *** qt_argv () |
Return argv
void removeArgs (const char *id) |
Remove named options.
Parameters:
id | The name of the options to be removed. |
void saveAppArgs ( QDataStream &) |
Save all but the Qt and KDE arguments to a stream.
void loadAppArgs ( QDataStream &) |
Load arguments from a stream.
void setOption (const QCString &option, bool enabled) |
Set a boolean option
void setOption (const QCString &option, const char *value) |
Set a string option
void addArgument (const char *argument) |
Add an argument
void save ( QDataStream &) |
Save to a stream.
void load ( QDataStream &) |
Restore from a stream.