• Skip to content
  • Skip to link menu
KDE API Reference
  • KDE API Reference
  • kdelibs API Reference
  • KDE Home
  • Contact Us
 

KDECore

Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
KCmdLineArgs Class Reference

#include <kcmdlineargs.h>

Public Types

enum  StdCmdLineArg {
  CmdLineArgQt = 0x01, CmdLineArgKDE = 0x02, CmdLineArgsMask =0x03, CmdLineArgNone = 0x00,
  Reserved = 0xff
}
 

Public Member Functions

QString arg (int n) const
 
void clear ()
 
int count () const
 
QString getOption (const QByteArray &option) const
 
QStringList getOptionList (const QByteArray &option) const
 
bool isSet (const QByteArray &option) const
 
KUrl url (int n) const
 

Static Public Member Functions

static const KAboutData * aboutData ()
 
static void addCmdLineOptions (const KCmdLineOptions &options, const KLocalizedString &name=KLocalizedString(), const QByteArray &id=QByteArray(), const QByteArray &afterId=QByteArray())
 
static void addStdCmdLineOptions (StdCmdLineArgs stdargs=StdCmdLineArgs(CmdLineArgQt|CmdLineArgKDE))
 
static void addTempFileOption ()
 
static QStringList allArguments ()
 
static QString appName ()
 
static QString cwd ()
 
static void enable_i18n ()
 
static void init (int argc, char **argv, const QByteArray &appname, const QByteArray &catalog, const KLocalizedString &programName, const QByteArray &version, const KLocalizedString &description=KLocalizedString(), StdCmdLineArgs stdargs=StdCmdLineArgs(CmdLineArgQt|CmdLineArgKDE))
 
static void init (int _argc, char **_argv, const KAboutData *about, StdCmdLineArgs stdargs=StdCmdLineArgs(CmdLineArgQt|CmdLineArgKDE))
 
static void init (const KAboutData *about)
 
static bool isTempFileSet ()
 
static void loadAppArgs (QDataStream &)
 
static KUrl makeURL (const QByteArray &urlArg)
 
static KCmdLineArgs * parsedArgs (const QByteArray &id=QByteArray())
 
static int & qtArgc ()
 
static char ** qtArgv ()
 
static void reset ()
 
static void saveAppArgs (QDataStream &)
 
static void setCwd (const QByteArray &cwd)
 
static void usage (const QByteArray &id=QByteArray())
 
static void usageError (const QString &error)
 

Protected Member Functions

 KCmdLineArgs (const KCmdLineOptions &_options, const KLocalizedString &_name, const QByteArray &_id)
 
 ~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, version, description);
// Define the command line options using KCmdLineOptions
KCmdLineOptions options;
....
// Register the supported options
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
QString anotherOptionArg = args->getOption("another-option");
// Arguments (e.g. files to open)
for(int i = 0; i < args->count(); i++) // Counting start at 0!
{
openFile( 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:

KCmdLineOptions options;
options.add("a", ki18n("A short binary option"));
options.add("b <file>", ki18n("A short option which takes an argument"));
options.add("c <speed>", ki18n("As above but with a default value"), "9600");
options.add("option1", ki18n("A long binary option, off by default"));
options.add("nooption2", ki18n("A long binary option, on by default"));
options.add(":", ki18n("Extra options:"));
options.add("option3 <file>", ki18n("A long option which takes an argument"));
options.add("option4 <speed>", ki18n("A long option which takes an argument, defaulting to 9600"), "9600");
options.add("d").add("option5", ki18n("A long option which has a short option as alias"));
options.add("e").add("nooption6", ki18n("Another long option with an alias"));
options.add("f").add("option7 <speed>", ki18n("'--option7 speed' is the same as '-f speed'"));
options.add("!option8 <cmd>", ki18n("All options following this one will be treated as arguments"));
options.add("+file", ki18n("A required argument 'file'"));
options.add("+[arg1]", ki18n("An optional argument 'arg1'"));
options.add("!+command", ki18n("A required argument 'command', that can contain multiple words, even starting with '-'"));
options.add("", ki18n("Additional help text not associated with any particular option"));

The ki18n calls are used for translation instead of the more usual i18n calls, because the translation needs to be delayed until after the message catalogs have been initialized.

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

is the same as:

myapp --nooption4

If an option value is provided multiple times, normally 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. 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

When an application does this it should mention this in the description of the option. To access these options, use getOptionList()

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 281 of file kcmdlineargs.h.

Member Enumeration Documentation

enum KCmdLineArgs::StdCmdLineArg
Enumerator
CmdLineArgQt 
CmdLineArgKDE 
CmdLineArgsMask 
CmdLineArgNone 
Reserved 

Definition at line 289 of file kcmdlineargs.h.

Constructor & Destructor Documentation

KCmdLineArgs::KCmdLineArgs ( const KCmdLineOptions &  _options,
const KLocalizedString &  _name,
const QByteArray &  _id 
)
protected

Constructor.

Constructor.

The given arguments are assumed to be constants.

Definition at line 1311 of file kcmdlineargs.cpp.

KCmdLineArgs::~KCmdLineArgs ( )
protected

Destructor.

use only.

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

Destructor.

Definition at line 1321 of file kcmdlineargs.cpp.

Member Function Documentation

const KAboutData * KCmdLineArgs::aboutData ( )
static

Returns the KAboutData for consumption by KComponentData.

Definition at line 1060 of file kcmdlineargs.cpp.

void KCmdLineArgs::addCmdLineOptions ( const KCmdLineOptions &  options,
const KLocalizedString &  name = KLocalizedString(),
const QByteArray &  id = QByteArray(),
const QByteArray &  afterId = QByteArray() 
)
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:

KCmdLineOptions options;
options.add("option1 <argument>", ki18n("Description 1"), "my_extra_arg");
options.add("o");
options.add("option2", ki18n("Description 2"));
options.add("nooption3", ki18n("Description 3"));
options.add("+file", ki18n("A required argument 'file'"));
  • "option1" is an option that requires an additional argument, but if one is not provided, it uses "my_extra_arg".
  • "option2" is an option that can be turned on. The default is off.
  • "option3" is an option that can be turned off. The default is on.
  • "o" does not have a description. It is an alias for the option that follows. In this case "option2".
  • "+file" specifies an argument. The '+' is removed. If your program doesn't specify that it can use arguments your program will abort when an argument is passed to it. Note that the reverse is not true. If required, you must check yourself the number of arguments specified by the user:
    KCmdLineArgs *args = KCmdLineArgs::parsedArgs();
    if (args->count() == 0) KCmdLineArgs::usage(i18n("No file specified"));

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:

  • "myapp --option1 test"
  • "myapp" (same as "myapp --option1 my_extra_arg")
  • "myapp --option2"
  • "myapp --nooption2" (same as "myapp", since it is off by default)
  • "myapp -o" (same as "myapp --option2")
  • "myapp --nooption3"
  • "myapp --option3 (same as "myapp", since it is on by default) @li "myapp –option2 –nooption2" (same as "myapp", because it option2 is off by default, and the last usage applies)
  • "myapp /tmp/file"
Parameters
optionsA list of options that your code supplies.
namethe name of the option list, as displayed by the help output. Can be empty.
idA name with which these options can be identified, can be empty.
afterIdThe options are inserted after this set of options, can be empty.

Definition at line 503 of file kcmdlineargs.cpp.

void KCmdLineArgs::addStdCmdLineOptions ( StdCmdLineArgs  stdargs = StdCmdLineArgs(CmdLineArgQt|CmdLineArgKDE))
static

add standard Qt/KDE command-line args

Add Qt and KDE command line options to KCmdLineArgs.

Definition at line 492 of file kcmdlineargs.cpp.

void KCmdLineArgs::addTempFileOption ( )
static

Add standard option –tempfile.

Definition at line 1603 of file kcmdlineargs.cpp.

QStringList KCmdLineArgs::allArguments ( )
static

Returns the list of command-line arguments.

Since
4.6

Definition at line 1616 of file kcmdlineargs.cpp.

QString KCmdLineArgs::appName ( )
static

Get the appname according to argv[0].

Returns
the name of the application

Definition at line 483 of file kcmdlineargs.cpp.

QString KCmdLineArgs::arg ( int  n) const

Read out an argument.

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

Definition at line 1552 of file kcmdlineargs.cpp.

void KCmdLineArgs::clear ( )

Clear all options and arguments.

Definition at line 1335 of file kcmdlineargs.cpp.

int KCmdLineArgs::count ( ) const

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

Returns
The number of arguments that aren't options

Definition at line 1546 of file kcmdlineargs.cpp.

QString KCmdLineArgs::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.

Returns
the current working directory

Definition at line 478 of file kcmdlineargs.cpp.

void KCmdLineArgs::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()).

Definition at line 1066 of file kcmdlineargs.cpp.

QString KCmdLineArgs::getOption ( const QByteArray &  option) const

Read out a string option.

The option must have a corresponding KCmdLineOptions entry of the form:

options.add("option <argument>", ki18n("Description"), "default");

You cannot test for the presence of an alias - you must always test for the full 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 once, the value of the last occurrence is used.

Definition at line 1438 of file kcmdlineargs.cpp.

QStringList KCmdLineArgs::getOptionList ( const QByteArray &  option) const

Read out all occurrences of a string option.

The option must have a corresponding KCmdLineOptions entry of the form:

options.add("option <argument>", ki18n("Description"), "default");

You cannot test for the presence of an alias - you must always test for the full option.

Parameters
optionThe name of the option, without '-' or '-no'.
Returns
A list of all option values. If no option was present on the command line, an empty list is returned.

Definition at line 1469 of file kcmdlineargs.cpp.

void KCmdLineArgs::init ( int  argc,
char **  argv,
const QByteArray &  appname,
const QByteArray &  catalog,
const KLocalizedString &  programName,
const QByteArray &  version,
const KLocalizedString &  description = KLocalizedString(),
StdCmdLineArgs  stdargs = StdCmdLineArgs(CmdLineArgQt|CmdLineArgKDE) 
)
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].
catalogTranslation catalog name, if empty appname will be used.
programNameA program name string to be used for display purposes. This string should be marked for translation. Example: ki18n("KEdit")
versionA version.
descriptionA short description of what your application is about. Also marked for translation.
stdargsKDE/Qt or no default parameters

Definition at line 418 of file kcmdlineargs.cpp.

void KCmdLineArgs::init ( int  _argc,
char **  _argv,
const KAboutData *  about,
StdCmdLineArgs  stdargs = StdCmdLineArgs(CmdLineArgQt|CmdLineArgKDE) 
)
static

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.

Parameters
_argcAs passed to main(...).
_argvAs passed to main(...).
aboutA KAboutData object describing your program.
stdargsKDE/Qt or no default parameters

Definition at line 449 of file kcmdlineargs.cpp.

void KCmdLineArgs::init ( const KAboutData *  about)
static

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, CmdLineArgNone).

Parameters
aboutthe about data.
See also
KAboutData

Definition at line 440 of file kcmdlineargs.cpp.

bool KCmdLineArgs::isSet ( const QByteArray &  option) const

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

Parameters
optionThe name of the option without '-' or '-no'.
Returns
The value of the option. It will be true if the option was specifically turned on in the command line, or if the option is turned on by default (in the KCmdLineOptions list) and was not specifically turned off in the command line. Equivalently, it will be false if the option was specifically turned off in the command line, or if the option is turned off by default (in the KCmdLineOptions list) and was not specifically turned on in the command line.

Definition at line 1496 of file kcmdlineargs.cpp.

bool KCmdLineArgs::isTempFileSet ( )
static
Returns
true if –tempfile was set

Definition at line 1610 of file kcmdlineargs.cpp.

void KCmdLineArgs::loadAppArgs ( QDataStream &  ds)
static

Load arguments from a stream.

Definition at line 560 of file kcmdlineargs.cpp.

KUrl KCmdLineArgs::makeURL ( const QByteArray &  urlArg)
static

Used by url().

Made public for apps that don't use KCmdLineArgs

Parameters
urlArgthe argument
Returns
the url.

Definition at line 1573 of file kcmdlineargs.cpp.

KCmdLineArgs * KCmdLineArgs::parsedArgs ( const QByteArray &  id = QByteArray())
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, can be empty.

Definition at line 611 of file kcmdlineargs.cpp.

int & KCmdLineArgs::qtArgc ( )
static

Returns the number of arguments returned by qtArgv()

See also
qtArgv

Definition at line 977 of file kcmdlineargs.cpp.

char ** KCmdLineArgs::qtArgv ( )
static

Returns command line options for consumption by Qt after parsing them in a way that is consistent with KDE's general command line handling.

In particular this ensures that Qt command line options can be specified as either -option or –option and that any options specified after '–' will be ignored.

See also
qt_argc

Definition at line 1011 of file kcmdlineargs.cpp.

void KCmdLineArgs::reset ( )
static

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 1342 of file kcmdlineargs.cpp.

void KCmdLineArgs::saveAppArgs ( QDataStream &  ds)
static

for KUniqueApplication only:

Save all but the Qt and KDE arguments to a stream.

Definition at line 534 of file kcmdlineargs.cpp.

void KCmdLineArgs::setCwd ( const QByteArray &  cwd)
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.

Parameters
cwdthe new working directory

Definition at line 1329 of file kcmdlineargs.cpp.

KUrl KCmdLineArgs::url ( int  n) const

Read out an argument representing a URL.

The argument can be

  • an absolute filename
  • a relative filename
  • a URL
Parameters
nThe argument to read. 0 is the first argument. count()-1 is the last argument.
Returns
a URL representing the n'th argument.

Definition at line 1568 of file kcmdlineargs.cpp.

void KCmdLineArgs::usage ( const QByteArray &  id = QByteArray())
static

Print the usage help to stdout and exit.

Parameters
idif empty, print all options. If id is set, only print the option specified by id. The id is the value set by addCmdLineOptions().

Definition at line 1095 of file kcmdlineargs.cpp.

void KCmdLineArgs::usageError ( const QString &  error)
static

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

Parameters
errorthe error to print

Definition at line 1080 of file kcmdlineargs.cpp.


The documentation for this class was generated from the following files:
  • kcmdlineargs.h
  • kcmdlineargs.cpp
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Mon Jun 22 2020 13:22:12 by doxygen 1.8.7 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.

KDECore

Skip menu "KDECore"
  • Main Page
  • Namespace List
  • Namespace Members
  • Alphabetical List
  • Class List
  • Class Hierarchy
  • Class Members
  • File List
  • File Members
  • Modules
  • Related Pages

kdelibs API Reference

Skip menu "kdelibs API Reference"
  • DNSSD
  • Interfaces
  •   KHexEdit
  •   KMediaPlayer
  •   KSpeech
  •   KTextEditor
  • kconf_update
  • KDE3Support
  •   KUnitTest
  • KDECore
  • KDED
  • KDEsu
  • KDEUI
  • KDEWebKit
  • KDocTools
  • KFile
  • KHTML
  • KImgIO
  • KInit
  • kio
  • KIOSlave
  • KJS
  •   KJS-API
  •   WTF
  • kjsembed
  • KNewStuff
  • KParts
  • KPty
  • Kross
  • KUnitConversion
  • KUtils
  • Nepomuk
  • Plasma
  • Solid
  • Sonnet
  • ThreadWeaver

Search



Report problems with this website to our bug tracking system.
Contact the specific authors with questions and comments about the page contents.

KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal