#include <tdecmdlineargs.h>

Public Member Functions
TQCString	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
static void	init (int _argc, char *_argv, const char _appname, const char programName, const char _description, const char *_version, bool noKApp=false)

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

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

static void	init (const TDEAboutData *about)

static void	addCmdLineOptions (const TDECmdLineOptions options, const char name=0, const char id=0, const char afterId=0)

static TDECmdLineArgs *	parsedArgs (const char *id=0)

static TQString	cwd ()

static const char *	appName ()

static void	usage (const char *id=0)

static void	usage (const TQString &error)

static void	enable_i18n ()

static KURL	makeURL (const char *urlArg)

static void	setCwd (char *cwd)

static void	reset ()

static void	loadAppArgs (TQDataStream &)

static void	addTempFileOption ()

static bool	isTempFileSet ()

Protected Member Functions
	TDECmdLineArgs (const TDECmdLineOptions _options, const char _name, const char *_id)

	~TDECmdLineArgs ()

Friends
class	TDEApplication

class	KUniqueApplication

class	TQPtrList< TDECmdLineArgs >

Detailed Description

A class for command-line argument handling.

TDECmdLineArgs 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 TDECmdLineArgs should look like this:

int main(int argc, char *argv[])
{
   // Initialize command line args
   TDECmdLineArgs::init(argc, argv, appName, programName, description, version);
 
   // Tell which options are supported
   TDECmdLineArgs::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 TDEApplication will usually do this in main but this is not
   // necessary.
   // A KUniqueApplication might want to handle it in newInstance().
 
   TDECmdLineArgs *args = TDECmdLineArgs::parsedArgs();
 
   // A binary option (on / off)
   if (args->isSet("some-option"))
      ....
 
   // An option which takes an additional argument
   TQCString 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( TQFile::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 TDECmdLineOptions class. An example is shown below:

static const TDECmdLineOptions 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 },
   TDECmdLineLastOption // 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 TDECmdLineArgs. 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

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 222 of file tdecmdlineargs.h.

Constructor & Destructor Documentation

◆ TDECmdLineArgs()

TDECmdLineArgs::TDECmdLineArgs	(	const TDECmdLineOptions *	_options,
		const char *	_name,
		const char *	_id
	)

protected

Constructor.

The given arguments are assumed to be constants.

Definition at line 991 of file tdecmdlineargs.cpp.

◆ ~TDECmdLineArgs()

TDECmdLineArgs::~TDECmdLineArgs ( )

protected

Destructor.

Definition at line 1003 of file tdecmdlineargs.cpp.

Member Function Documentation

◆ addCmdLineOptions()

void TDECmdLineArgs::addCmdLineOptions	(	const TDECmdLineOptions *	options,
		const char *	name = `0`,
		const char *	id = `0`,
		const char *	afterId = `0`
	)

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 TDECmdLineOptions 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 },
   TDECmdLineLastOption
}

"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:
TDECmdLineArgs *args = TDECmdLineArgs::parsedArgs();

if (args->count() == 0) TDECmdLineArgs::usage(i18n("No file specified!"));

TDECmdLineArgs::usage
static void usage(const char *id=0)
Print the usage help to stdout and exit.
Definition: tdecmdlineargs.cpp:774

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

options	A list of options that your code supplies.
name	the name of the option, can be 0.
id	A name with which these options can be identified, can be 0.
afterId	The options are inserted after this set of options, can be 0.

Definition at line 206 of file tdecmdlineargs.cpp.

◆ addTempFileOption()

void TDECmdLineArgs::addTempFileOption ( )

static

Add standard option –tempfile.

Since: 3.4

Definition at line 1289 of file tdecmdlineargs.cpp.

◆ appName()

const char * TDECmdLineArgs::appName ( )

static

Get the appname according to argv[0].

Returns: the name of the application

Definition at line 199 of file tdecmdlineargs.cpp.

◆ arg()

const char * TDECmdLineArgs::arg ( int n ) const

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 * pointer to the n'th argument.

Definition at line 1232 of file tdecmdlineargs.cpp.

◆ clear()

void TDECmdLineArgs::clear ( )

Clear all options and arguments.

Definition at line 1012 of file tdecmdlineargs.cpp.

◆ count()

int TDECmdLineArgs::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 1224 of file tdecmdlineargs.cpp.

◆ cwd()

TQString TDECmdLineArgs::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 194 of file tdecmdlineargs.cpp.

◆ enable_i18n()

void TDECmdLineArgs::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 745 of file tdecmdlineargs.cpp.

◆ getOption()

TQCString TDECmdLineArgs::getOption ( const char * option ) const

Read out a string option.

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

{ "option <argument>", I18N_NOOP("Description"), "default" }

You cannot test for the presence of an alias - you must always test for the full 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. If the option was present more than the value of the last occurrence is used.

Definition at line 1119 of file tdecmdlineargs.cpp.

◆ getOptionList()

QCStringList TDECmdLineArgs::getOptionList ( const char * option ) const

Read out all occurrences of a string option.

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

{ "option <argument>", I18N_NOOP("Description"), "default" }

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

Parameters

option The 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 1151 of file tdecmdlineargs.cpp.

◆ init() [1/4]

void TDECmdLineArgs::init ( const TDEAboutData * 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 TDEAboutData information. This method is exactly the same as calling init(0,0, const TDEAboutData *about, true).

Parameters

about the about data.

See also: TDEAboutData

Definition at line 153 of file tdecmdlineargs.cpp.

◆ init() [2/4]

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

static

Deprecated:: You should convert any calls to this method to use the one above, by adding in the program name to be used for display purposes.

Do not forget to mark it for translation using I18N_NOOP.

Definition at line 136 of file tdecmdlineargs.cpp.

◆ init() [3/4]

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

static

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].
programName	A program name string to be used for display purposes. This string should be marked for translation. Example: I18N_NOOP("KEdit")
_description	A short description of what your application is about.
_version	A version.
noKApp	Set this true to not add commandline options for TQApplication / TDEApplication

Since: 3.2

Definition at line 127 of file tdecmdlineargs.cpp.

◆ init() [4/4]

void TDECmdLineArgs::init	(	int	_argc,
		char **	_argv,
		const TDEAboutData *	about,
		bool	noKApp = `false`
	)

static

Initialize class.

This function should be called as the very first thing in your application. It uses TDEAboutData to replace some of the arguments that would otherwise be required.

Parameters

_argc	As passed to `main(...)`.
_argv	As passed to `main(...)`.
about	A TDEAboutData object describing your program.
noKApp	Set this true to not add commandline options for TQApplication / TDEApplication

Definition at line 162 of file tdecmdlineargs.cpp.

◆ isSet()

bool TDECmdLineArgs::isSet ( const char * option ) const

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

Parameters

option The 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 TDECmdLineOptions 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 TDECmdLineOptions list) and was not specifically turned on in the command line.

Definition at line 1181 of file tdecmdlineargs.cpp.

◆ isTempFileSet()

bool TDECmdLineArgs::isTempFileSet ( )

static

Returns: true if –tempfile was set

Since: 3.4

Definition at line 1294 of file tdecmdlineargs.cpp.

◆ loadAppArgs()

void TDECmdLineArgs::loadAppArgs ( TQDataStream & ds )

static

Load arguments from a stream.

Definition at line 264 of file tdecmdlineargs.cpp.

◆ makeURL()

KURL TDECmdLineArgs::makeURL ( const char * urlArg )

static

Used by url().

Made public for apps that don't use TDECmdLineArgs

Parameters

urlArg the argument

Returns: the url.

Definition at line 1253 of file tdecmdlineargs.cpp.

◆ parsedArgs()

TDECmdLineArgs * TDECmdLineArgs::parsedArgs ( const char * id = 0 )

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

id	The name of the options you are interested in, can be 0.

Definition at line 310 of file tdecmdlineargs.cpp.

◆ reset()

void TDECmdLineArgs::reset ( )

static

Reset all option definitions, i.e.

cancel all addCmdLineOptions calls. Note that TDEApplication's options are removed too, you might want to call TDEApplication::addCmdLineOptions if you want them back.

You usually don't want to call this method.

Definition at line 1021 of file tdecmdlineargs.cpp.

◆ setCwd()

static void TDECmdLineArgs::setCwd ( char * cwd )

inlinestatic

Made public for apps that don't use TDECmdLineArgs To be done before makeURL, to set the current working directory in case makeURL needs it.

Parameters

cwd	the new working directory

Definition at line 516 of file tdecmdlineargs.h.

◆ url()

KURL TDECmdLineArgs::url ( int n ) const

Read out an argument representing a URL.

The argument can be

an absolute filename
a relative filename
a URL

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.

Definition at line 1248 of file tdecmdlineargs.cpp.

◆ usage() [1/2]

void TDECmdLineArgs::usage ( const char * id = 0 )

static

Print the usage help to stdout and exit.

Parameters

id	if 0, 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 774 of file tdecmdlineargs.cpp.

◆ usage() [2/2]

void TDECmdLineArgs::usage ( const TQString & error )

static

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

Parameters

error the error to print

Definition at line 759 of file tdecmdlineargs.cpp.

The documentation for this class was generated from the following files:

tdecore

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ TDECmdLineArgs()

◆ ~TDECmdLineArgs()

Member Function Documentation

◆ addCmdLineOptions()

◆ addTempFileOption()

◆ appName()

◆ arg()

◆ clear()

◆ count()

◆ cwd()

◆ enable_i18n()

◆ getOption()

◆ getOptionList()

◆ init() [1/4]

◆ init() [2/4]

◆ init() [3/4]

◆ init() [4/4]

◆ isSet()

◆ isTempFileSet()

◆ loadAppArgs()

◆ makeURL()

◆ parsedArgs()

◆ reset()

◆ setCwd()

◆ url()

◆ usage() [1/2]

◆ usage() [2/2]

tdecore

tdecore