KCmdLineArgs Class Reference
A class for command-line argument handling. More...
#include <kcmdlineargs.h>
Collaboration diagram for KCmdLineArgs:

Public Member Functions | |
QCString | getOption (const char *option) const |
QCStringList | getOptionList (const char *option) const |
bool | isSet (const char *option) const |
int | count () const |
const char * | arg (int n) const |
KURL | url (int n) const |
void | clear () |
Static Public Member Functions | |
void | init (int _argc, char **_argv, const char *_appname, const char *programName, const char *_description, const char *_version, bool noKApp=false) |
void | init (int _argc, char **_argv, const char *_appname, const char *_description, const char *_version, bool noKApp=false) KDE_DEPRECATED |
void | init (int _argc, char **_argv, const KAboutData *about, bool noKApp=false) |
void | init (const KAboutData *about) |
void | addCmdLineOptions (const KCmdLineOptions *options, const char *name=0, const char *id=0, const char *afterId=0) |
KCmdLineArgs * | parsedArgs (const char *id=0) |
QString | cwd () |
const char * | appName () |
void | usage (const char *id=0) |
void | usage (const QString &error) |
void | enable_i18n () |
KURL | makeURL (const char *urlArg) |
void | setCwd (char *cwd) |
void | reset () |
void | loadAppArgs (QDataStream &) |
void | addTempFileOption () |
bool | isTempFileSet () |
Protected Member Functions | |
KCmdLineArgs (const KCmdLineOptions *_options, const char *_name, const char *_id) | |
~KCmdLineArgs () | |
Friends | |
class | KApplication |
class | KUniqueApplication |
class | QPtrList<KCmdLineArgs> |
Detailed Description
A class for command-line argument handling.KCmdLineArgs provides simple access to the command-line arguments for an application. 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 using KCmdLineArgs should look like this:
int main(int argc, char *argv[]) { // Initialize command line args KCmdLineArgs::init(argc, argv, appName, programName, 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/arguments // A KApplication will usually do this in main but this is not // necessary. // 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. .... }
The options that an application supports are configured using the KCmdLineOptions class. An example is shown below:
static const 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 }, { ":", I18N_NOOP("Extra options:"), 0 }, { "option3 <file>", I18N_NOOP("A long option which takes an argument"), 0 }, { "option4 <speed>", I18N_NOOP("A long option which takes an argument, defaulting to 9600"), "9600" }, { "d", 0, 0 }, { "option5", I18N_NOOP("A long option which has a short option as alias"), 0 }, { "e", 0, 0 }, { "nooption6", I18N_NOOP("Another long option with an alias"), 0 }, { "f", 0, 0 }, { "option7 <speed>", I18N_NOOP("'--option7 speed' is the same as '-f speed'"), 0 }, { "!option8 <cmd>", I18N_NOOP("All options following this one will be treated as arguments"), 0 }, { "+file", I18N_NOOP("A required argument 'file'"), 0 }, { "+[arg1]", I18N_NOOP("An optional argument 'arg1'"), 0 }, { "!+command", I18N_NOOP("A required argument 'command', that can contain multiple words, even starting with '-'"), 0 }, { "", I18N_NOOP("Additional help text not associated with any particular option") 0 }, KCmdLineLastOption // 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 an alias, a program should only test 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
myapp --nooption4
If an option value is provided multiple times, normally only the last value is used:
myapp -c 1200 -c 2400 -c 4800
myapp -c 4800
However, an application can choose to use all values specified as well. As an example of this, consider that you may wish to specify a number of directories to use:
myapp -I /usr/include -I /opt/kde/include -I /usr/X11/include
Tips for end-users:
- Single char options like "-a -b -c" may be combined into "-abc"
- The option "--foo bar" may also be written "--foo=bar"
- The option "-P lp1" may also be written "-P=lp1" or "-Plp1"
- The option "--foo bar" may also be written "-foo bar"
- Author:
- Waldo Bastian
- Version:
- 0.0.4
Definition at line 222 of file kcmdlineargs.h.
Constructor & Destructor Documentation
|
Constructor. The given arguments are assumed to be constants. Definition at line 974 of file kcmdlineargs.cpp. Referenced by addCmdLineOptions(). |
|
Destructor.
Definition at line 986 of file kcmdlineargs.cpp. |
Member Function Documentation
|
Initialize class. This function should be called as the very first thing in your application.
Definition at line 127 of file kcmdlineargs.cpp. Referenced by init(). |
|
Definition at line 136 of file kcmdlineargs.cpp. References init(). |
|
Initialize class. This function should be called as the very first thing in your application. It uses KAboutData to replace some of the arguments that would otherwise be required.
Definition at line 162 of file kcmdlineargs.cpp. References KApplication::addCmdLineOptions(), and KStaticDeleter< type >::setObject(). |
|
Initialize Class. This function should be called as the very first thing in your application. This method will rarely be used, since it doesn't provide any argument parsing. It does provide access to the KAboutData information. This method is exactly the same as calling init(0,0, const KAboutData *about, true).
Definition at line 153 of file kcmdlineargs.cpp. References KAboutData::appName(), and init(). |
|
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"), "my_extra_arg" }, { "o", 0, 0 }, { "option2", I18N_NOOP("Description 2"), 0 }, { "nooption3", I18N_NOOP("Description 3"), 0 }, KCmdLineLastOption }
cmd = myapp [options] file options = (option)* option = --option1 \<argument> | (-o | --option2 | --nooption2) | ( --option3 | --nooption3 ) Instead of "--option3" one may also use "-option3" Usage examples:
Definition at line 206 of file kcmdlineargs.cpp. References id, and KCmdLineArgs(). Referenced by KUniqueApplication::addCmdLineOptions(), KApplication::addCmdLineOptions(), and addTempFileOption(). |
|
Access parsed arguments. This function returns all command line arguments that your code handles. If unknown command-line arguments are encountered the program is aborted and usage information is shown.
Definition at line 308 of file kcmdlineargs.cpp. References id. Referenced by KApplication::dcopClient(), isTempFileSet(), and KUniqueApplication::start(). |
|
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.
Definition at line 194 of file kcmdlineargs.cpp. Referenced by makeURL(). |
|
Get the appname according to argv[0].
Definition at line 199 of file kcmdlineargs.cpp. |
|
Print the usage help to stdout and exit.
Definition at line 757 of file kcmdlineargs.cpp. References arg(), KCmdLineOptions::def, KCmdLineOptions::description, enable_i18n(), id, name, KCmdLineOptions::name, options, and KAboutData::shortDescription(). |
|
Print an error to stderr and the usage help to stdout and exit.
Definition at line 742 of file kcmdlineargs.cpp. |
|
Enable i18n to be able to print a translated error message. N.B.: This function leaks memory, therefore you are expected to exit afterwards (e.g., by calling usage()). Definition at line 728 of file kcmdlineargs.cpp. References KInstance::config(). Referenced by usage(). |
|
Read out a string option. The option must have a corresponding KCmdLineOptions entry of the form: { "option <argument>", I18N_NOOP("Description"), "default" }
Definition at line 1102 of file kcmdlineargs.cpp. Referenced by KApplication::dcopClient(). |
|
Read out all occurrences of a string option. The option must have a corresponding KCmdLineOptions entry of the form: { "option <argument>", I18N_NOOP("Description"), "default" }
Definition at line 1134 of file kcmdlineargs.cpp. |
|
Read out a boolean option or check for the presence of string option.
Definition at line 1164 of file kcmdlineargs.cpp. Referenced by KApplication::dcopClient(), isTempFileSet(), and KUniqueApplication::start(). |
|
Read the number of arguments that aren't options (but, for example, filenames).
Definition at line 1207 of file kcmdlineargs.cpp. |
|
Read out an argument.
Definition at line 1215 of file kcmdlineargs.cpp. |
|
Read out an argument representing a URL. The argument can be
Definition at line 1231 of file kcmdlineargs.cpp. |
|
Used by url(). Made public for apps that don't use KCmdLineArgs
Definition at line 1236 of file kcmdlineargs.cpp. References KURL::cleanPath(), cwd(), KURL::isRelativeURL(), and KURL::setPath(). Referenced by url(). |
|
Made public for apps that don't use KCmdLineArgs To be done before makeURL, to set the current working directory in case makeURL needs it.
Definition at line 516 of file kcmdlineargs.h. |
|
Clear all options and arguments.
Definition at line 995 of file kcmdlineargs.cpp. Referenced by loadAppArgs(), and reset(). |
|
Reset all option definitions, i.e. cancel all addCmdLineOptions calls. Note that KApplication's options are removed too, you might want to call KApplication::addCmdLineOptions if you want them back. You usually don't want to call this method. Definition at line 1004 of file kcmdlineargs.cpp. References clear(). |
|
Load arguments from a stream.
Definition at line 264 of file kcmdlineargs.cpp. References clear(), id, load(), and KStaticDeleter< type >::setObject(). |
|
Add standard option --tempfile
Definition at line 1271 of file kcmdlineargs.cpp. References addCmdLineOptions(). |
|
Definition at line 1276 of file kcmdlineargs.cpp. References isSet(), and parsedArgs(). |
The documentation for this class was generated from the following files: