Application Class Reference

Base functionality for an application, including command-line argument parsing and a shutdown handler. More...

#include <Application.h++>

Inheritance diagram for Application:

[legend]

List of all members.

Classes
class	CommandOption
Public Member Functions
	Application (int argc, char **argv, const String &version="0.0", const String &compileDate="", const String &compileTime="")
	Construct a new Application.
virtual	~Application ()
	Destructor.
Protected Member Functions
virtual void	shutdown ()
	Shutdown method.
bool	registerOption (char opt, const String &longOpt, const String &argName, const String &desc)
	Register a command-line option.
bool	parseOptions (int argc, char **argv, int &index)
	Parse the command line options.
virtual bool	processOption (char opt, const String &longOpt, const char *arg=NULL)
	Process a command-line option.
virtual void	printUsage ()
	Print the usage text.
void	printError (const char *message,...)
	Print an error message.

---

Detailed Description

Base functionality for an application, including command-line argument parsing and a shutdown handler.

This class is implicitly a singleton; there can be only one instantiation of the class per process. The class should be subclassed and instantiated within the program's main() function.

Author:

Mark Lindner

---

Constructor & Destructor Documentation

Application	(	int	argc,
		char **	argv,
		const String &	version = "0.0",
		const String &	compileDate = "",
		const String &	compileTime = ""
	)

Construct a new Application.

Parameters:

	argc	The argument count (from main()).
	argv	The argument list (from main()).
	version	The optional version of the program; if not supplied, it defaults to "0.0".
	compileDate	The optional compile date of the program; typically provided by the compiler-defined macro __DATE__.
	compileTime	The optional compile time of the program; typically provided by the compiler-defined macro __TIME__.

~Application

(

)

[virtual]

Destructor.

---

Member Function Documentation

bool parseOptions	(	int	argc,
		char **	argv,
		int &	index
	)			[protected]

Parse the command line options.

This method should be called from the constructor at the appropriate time, after any application-specific options have been registered and any other necessary initialization has been completed.

Parameters:

	argc	The argument count.
	argv	The argument list.
	index	Upon return, the index of the first non-option argument.

Returns:

true if the options were parsed successfully, or false if there was a parsing error. (Parsing errors are reported to stderr as a side-effect.)

void printError	(	const char *	message,
			...
	)			[protected]

Print an error message.

The program name is automatically prepended to the message.

void printUsage

(

)

[protected, virtual]

Print the usage text.

bool processOption	(	char	opt,
		const String &	longOpt,
		const char *	arg = NULL
	)			[protected, virtual]

Process a command-line option.

This method is called for each registered option that is encountered on the command line during the call to parseOptions().

The Application class registers the "--help" and "--version" command line options automatically. Therefore a subclass should override processOption() such that if it does not recognize the option, it will call Application::processOption() to give it a chance to process it.

Parameters:

	opt	The one-character switch, or NUL if not applicable.
	longOpt	The long name for the switch, or String::null if not applicable.
	arg	The argument for the switch, or NULL if not applicable.

Returns:

true if the option was processed successfully, false otherwise.

Reimplemented in Service.

bool registerOption	(	char	opt,
		const String &	longOpt,
		const String &	argName,
		const String &	desc
	)			[protected]

Register a command-line option.

The option may have a short (one character) form and/or a long form. A typical invocation might look like this:

registerOption('o', "output", "file", "Specify @@ as the output file.");

The corresponding usage help text for this switch would appear as:

 -o <file>
 --output=<file>    - Specify <file> as the output file.
 

Parameters:

	opt	The one-character switch (e.g., 'v' for "-v"), or NUL if not applicable.
	longOpt	The long name for the switch (e.g., "verbose" for "--verbose"), or String::null if not applicable.
	argName	A token describing the argument for the switch, or the empty string "" if the switch does not accept an argument.
	desc	The description of the option, used in generating the usage text. Any occurrence of the token "@@" within the description will be replaced with a stylized form of the argument name, either by underlining the token or by enclosing it within angle brackets.

Returns:

true if the option was registered successfully, false otherwise. Attempts to register an existing option will fail.

void shutdown

(

)

[protected, virtual]

Shutdown method.

This method is called automatically when the application is terminated via a keyboard interrupt (typically Control-C). Subclasses may provide application-specific cleanup logic in this method. Since this method gets called from a signal handler, it should only perform minimal processing. It is not necessary for this method to call exit(), as that will be done automatically by the Application class.

The default implementation does nothing.

Reimplemented in Service.

---

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

• Application.h++
• Application.c++