class KCmdLineArgs

A class for command-line argument handling. More...

Definition#include <kcmdlineargs.h>
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

Public Methods

Public Static Methods

Protected Methods


Detailed Description

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 ", I18N_NOOP("A short option which takes an argument."), 0 },
     { "c ", 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 ", I18N_NOOP("A long option which takes an argument."), 0 },
     { "option3 ", 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 ", I18N_NOOP("'--option6 speed' is same a '-f speed'"), 0 },
     { "!option7 ", 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 },
     { 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

Normally if an option value is provided multiple times only the last value is used:


     myapp -c 1200 -c 2400 -c 4800

is usually the same as:


     myapp -c 4800

However, an application can choose to use all values specified as well. E.g. to specify a number of directories to use:


     myapp -I /usr/include -I /opt/kde/include -I /usr/X11/include

When an application does this it should mention this in the description of the option. getOptionList()

void  init (int _argc, char **_argv, const char *_appname, const char *_description, const char *_version, bool noKApp = false)

init

[static]

Initialize class.

This function should be called as the very first thing in your application.

Parameters:
argcAs passed to main(...).
argvAs passed to main(...).
appnameThe untranslated name of your application. This should match with argv[0].
descriptionA short description of what your application is about.
versionA version.
noKAppDon't add commandline options for QApplication/KApplication

void  init (int _argc, char **_argv, const KAboutData *about, bool noKApp = false)

init

[static]

Initialize class.

This function should be called as the very first thing in your application.

Parameters:
argcAs passed to main(...).
argvAs passed to main(...).
aboutA KAboutData object describing your program.
noKAppDon't add commandline options for QApplication / KApplication

void  init (const KAboutData *about)

init

[static]

Initialize Class

This function should be called as the very first thing in your application. This method is exactly the same as calling init(0,0, const KAboutData *about, true) This method will rarely be used

void  addCmdLineOptions ( const KCmdLineOptions *options, const char *name=0, const char *id = 0, const char *afterId=0)

addCmdLineOptions

[static]

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 ", 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 | (-o | --option2 | --nooption2) | ( --option3 | --nooption3 )

Instead of "--option3" one may also use "-option3"

Usage examples:

Parameters:
optionsA list of options thath your code supplies.
idA name with which these options can be identified.
afterIdThe options are inserted after this set of options.

KCmdLineArgsparsedArgs (const char *id=0)

parsedArgs

[static]

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.

Parameters:
idThe name of the options you are interested in.

QString  cwd ()

cwd

[static]

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.

const char * appName ()

appName

[static]

Get the appname according to argv[0]

void  usage (const char *id = 0)

usage

[static]

Print the usage help to stdout and exit.

Parameters:
completeIf true, print all available options.

void  usage (const QString &error)

usage

[static]

Print an error to stderr and the usage help to stdout and exit.

void  enable_i18n ()

enable_i18n

[static]

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()).

QCString  getOption (const char *option)

getOption

Read out a string option.

Parameters:
optionThe 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. If the option was present more than the value of the last occurence is used.

QCStringList  getOptionList (const char *option)

getOptionList

Read out all occurences of a string option.

Parameters:
optionThe name of the option without '-'.

Returns: A list of all option values. If no option was present on the command line, an empty list is returned.

bool  isSet (const char *option)

isSet

Read out a boolean option or check for the presence of string option.

If the option is listed as '

Parameters:
optionThe name of the option without '-' or '-no'.

Returns: The value of the option. If the option was not present on the command line the default is returned. If the option is listed as 'no

int  count ()

count

Read the number of arguments that aren't options (but, for example, filenames).

Returns: The number of arguments that aren't options

const char * arg (int n)

arg

Read out an argument.

Parameters:
nThe 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)

url

Read out an argument representing a URL.

The argument can be

Parameters:
nThe argument to read. 0 is the first argument. count()-1 is the last argument.

Returns: a URL representing the n'th argument.

KURL  makeURL ( const char * urlArg )

makeURL

[static]

Used by url Made public for apps that don't use KCmdLineArgs

Parameters:
urlArgsthe argument

void  setCwd ( char * cwd )

setCwd

[static]

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.

void  clear ()

clear

Clear all options and arguments.

 KCmdLineArgs ( const KCmdLineOptions *_options, const char *_id, const char *_name)

KCmdLineArgs

[protected]

Constructor.

 ~KCmdLineArgs ()

~KCmdLineArgs

[protected]

Use clear() if you want to free up some memory.

Destructor.