A class for managing application configuration and execution.

Derived classes should implement at a minimum

virtual void setupConfig();
virtual void loadConfig();
virtual int execute();

These are executed in the order shown by the call to main().

This class uses a cascaded configuration system. The application configuration is built up from the following sources, in increasing order of precedence:

A global configuration file
A user configuration file (which may be specified relative to the users home directory)
A local configuration file (in the pwd)
A configuration file specified on the command line
The command line

At each step in the above order, values read from that configuration source override any previous settings. So the command line has the highest precedence.

The configuration is set up and accessed using an object of type appConfigurator named config. For specification of the configuration file syntax and command line arguments see appConfigurator.

The configuration should be set up in the setupConfig function. This is normally done using the appConfigurator::add method, as in:

void derived_class::setupConfig()
{
   config.add("name", "s", "long", argType::Required, "section", "keyword", false, "int", "help message");
}

The configuration is then accessed using the config member's operator as in

void derived_class::loadConfig()
{
     int val = 0;
     config(val, "name");
}

In these examples, a config target with name "name" is created. If the user sets a value of 2 via the command line with -s 2, --long=2 or in a configuration file with

[section]
keyword=2

then val will be set to 2. Otherwise, val will remain 0.

Standard target -h/--help with name "help" to trigger printing a help message, and -c/--config with name "config" to pass a config file via the command line. This behavior can be changed by overriding functions.

Note: After loadConfig() but before execute(), the containers in config are de-allocated , so they can not be used inside execute.

A standard help message is produced when requested by the -h/--help option. This behavior can be changed by overriding the help method.

Definition at line 97 of file application.hpp.

#include <app/application.hpp>

Public Member Functions
int	main (int argc, char **argv)
	The application main function. More...

void	setConfigPathGlobal (const std::string &s)
	Set the global configuration path. More...

void	setConfigPathUser (const std::string &s)
	Set the user configuration path. More...

void	setConfigPathLocal (const std::string &s)
	Set the local configuration path. More...

Protected Member Functions
Required Overrides
These methods should be implemented in derived classes to use an mx::application in its default behavior.
virtual void	setupConfig ()
	In derived classes this is where the config targets are added to config. More...

virtual void	loadConfig ()
	Override this function to extract the configured values and set up the application. More...

virtual int	execute ()
	This function is where the derived class should do its work. More...

Optional Overrides
These methods do not need to be implemented in derived classes unless it is desired to change behavior.
virtual void	setup (int argc, char **argv)
	Sets up the application by executing the configuration steps. More...

int	reReadConfig ()
	Re-read the config stack. More...

virtual void	setDefaults (int argc, char **argv)
	Set the default search paths for config files. More...

virtual void	setupStandardConfig ()
	Set up the command-line config option in a standard way. More...

virtual void	setupStandardHelp ()
	Set up the help an options in a standard way. More...

virtual void	loadStandardConfig ()
	Loads the values of "config". More...

virtual void	loadStandardHelp ()
	Loads the value of "help" into doHelp. More...

virtual void	optionHelp (configTarget &tgt, ioutils::textTable &tt)
	Format a configTarget for the help message. More...

virtual void	setupBasicConfig ()
	Setup a basic configuration. Can be used in an intermediate derived class to allow its children to use setupConfig. More...

virtual void	loadBasicConfig ()
	Load a basic configuration. Can be used in an intermediate derived class to allow its children to use loadConfig. More...

virtual void	checkConfig ()
	Check the config. This is called at the end of setup, before the configuration is cleared. More...

virtual void	help ()
	Print a formatted help message, based on the config target inputs. More...

Protected Attributes
std::string	invokedName
	The name used to invoke this application. More...

std::string	m_configPathGlobal
	The path to the gobal configuration file. Set in constructor to use. More...

std::string	m_configPathGlobal_env
	Environment variable to check for the global config path. Set in constructor to use. More...

std::string	m_configPathUser
	The path to the user's configuration file. If the first character is not '/' or '~', this is added to HOME. Set in constructor to use. More...

std::string	m_configPathUser_env
	Environment variable to check fo the user config path. Set in constructor to use. More...

std::string	m_configPathLocal
	The path to a local configuration file. Set in constructor to use. More...

std::string	m_configPathLocal_env
	Environment variable to check for the local config path. Set in constructor to use. More...

bool	m_requireConfigPathLocal {true}
	Flag controlling whether lack of a local configuration file should be reported. More...

std::string	m_configPathCL
	The path to a configuration file specified on the command line. More...

std::string	m_configPathCLBase
	A base path to add to the CL path. Set in constructor to use. More...

std::string	m_configPathCLBase_env
	Environment variable to check for the CL base path. Set in constructor to use. More...

appConfigurator	config
	The structure used for parsing and storing the configuration. More...

bool	m_preserveConfig {false}
	Flag controlling whether the configuration is cleared before execution. Set in derived constructor. More...

bool	doHelp {false}
	Flag to control whether the help message is printed or not. More...

int	m_helpWidth {120}
	The total text width available for the help message. More...

int	m_helpSOColWidth {2}
	The width of the short option (-o) column in the help message. More...

int	m_helpLOColWidth {25}
	The width of the long option (–option) column in the help message. More...

int	m_helpCFColWidth {25}
	The width of the config file option column in the help message. More...

int	m_helpTypeColWidth {15}
	The width of the argument type column in the help message. More...

int	m_argc
	Store argc for later use. E.g. in reReadConfig(). More...

char **	m_argv
	Store argv for later use. E.g. in reReadConfig(). More...

Member Function Documentation

◆ checkConfig()

void mx::app::application::checkConfig ( )

protectedvirtual

Check the config. This is called at the end of setup, before the configuration is cleared.

It is up to you to decide how to handle the outcome. If a bad config results in printing help, you can set the doHelp flag.

Definition at line 221 of file application.cpp.

Referenced by setup().

◆ execute()

int mx::app::application::execute ( )

protectedvirtual

This function is where the derived class should do its work.

The application will exit with the return value of execute.

Definition at line 87 of file application.cpp.

Referenced by main().

◆ help()

void mx::app::application::help ( )

protectedvirtual

Print a formatted help message, based on the config target inputs.

Definition at line 268 of file application.cpp.

References mx::app::appConfigurator::clOnlyTargets, config, invokedName, mx::ioutils::textTable::m_colSep, mx::ioutils::textTable::m_colWidths, m_helpCFColWidth, m_helpLOColWidth, m_helpSOColWidth, m_helpTypeColWidth, m_helpWidth, mx::ioutils::textTable::m_lineStart, mx::ioutils::textTable::m_rows, mx::ioutils::textTable::m_rowSep, mx::app::appConfigurator::m_targets, optionHelp(), and mx::ioutils::textTable::outPut().

Referenced by main().

◆ loadBasicConfig()

void mx::app::application::loadBasicConfig ( )

protectedvirtual

Load a basic configuration. Can be used in an intermediate derived class to allow its children to use loadConfig.

This is called just before loadConfig().

Definition at line 216 of file application.cpp.

Referenced by setup().

◆ loadConfig()

void mx::app::application::loadConfig ( )

protectedvirtual

Override this function to extract the configured values and set up the application.

Definition at line 82 of file application.cpp.

Referenced by setup().

◆ loadStandardConfig()

void mx::app::application::loadStandardConfig ( )

protectedvirtual

Loads the values of "config".

Override this function if you do not want to use this, or have different behavior. See also setupStandardConfig().

Definition at line 200 of file application.cpp.

References config, m_configPathCL, and m_configPathCLBase.

Referenced by setup().

◆ loadStandardHelp()

void mx::app::application::loadStandardHelp ( )

protectedvirtual

Loads the value of "help" into doHelp.

Override this function if you do not want to use this, or have different behavior. See also setupStandardConfig().

Definition at line 206 of file application.cpp.

References config, and doHelp.

Referenced by setup().

◆ main()

int mx::app::application::main	(	int	argc,
		char **	argv
	)

The application main function.

Call this from the true main function, passing the command line arguments to be processed. This calls setup(), then checks if the doHelp flag was set. If so, it calls help() and returns. If doHelp is not set, it then clears the config structure, and then calls execute().

The configuration is cleared before the call to execute, unless m_preserveConfig = true.

Returns: 1 if help is executed.; -1 on error.; the value of execute() otherwise.

Parameters

[in]	argc	standard command line result specifying number of argumetns in argv
[in]	argv	standard command line result containing the arguments.

Definition at line 39 of file application.cpp.

References mx::app::appConfigurator::clear(), config, doHelp, execute(), help(), m_argc, m_argv, m_preserveConfig, and setup().

◆ optionHelp()

void mx::app::application::optionHelp	(	configTarget &	tgt,
		ioutils::textTable &	tt
	)

protectedvirtual

Format a configTarget for the help message.

Parameters

[in]	tgt	The Target
[out]	tt	the textTable being populated

Definition at line 226 of file application.cpp.

References mx::ioutils::textTable::addCell(), mx::app::configTarget::helpExplanation, mx::app::configTarget::helpType, mx::app::configTarget::keyword, mx::app::configTarget::longOpt, mx::app::configTarget::orderAdded, mx::app::configTarget::section, and mx::app::configTarget::shortOpt.

Referenced by help().

◆ reReadConfig()

int mx::app::application::reReadConfig ( )

protected

Re-read the config stack.

This would be used if some config targets can only be constructed after a first pass. Note that all previously read values will be appended as if entered twice, so you must be careful to only access new targets after calling this.

Returns: 0 on success.; -1 on error.

Definition at line 128 of file application.cpp.

References config, m_argc, m_argv, m_configPathCL, m_configPathGlobal, m_configPathLocal, m_configPathUser, mx::app::appConfigurator::parseCommandLine(), and mx::app::appConfigurator::readConfig().

◆ setConfigPathGlobal()

void mx::app::application::setConfigPathGlobal ( const std::string & s )

Set the global configuration path.

Parameters

[in] s the new path

Definition at line 62 of file application.cpp.

References m_configPathGlobal.

◆ setConfigPathLocal()

void mx::app::application::setConfigPathLocal ( const std::string & s )

Set the local configuration path.

Parameters

[in] s the new path

Definition at line 72 of file application.cpp.

References m_configPathLocal.

◆ setConfigPathUser()

void mx::app::application::setConfigPathUser ( const std::string & s )

Set the user configuration path.

If the provided path does not star with a '/' or '~', then it will appended to the users HOME directory obtained from the environment.

Parameters

[in] s the new path to the user config file

Definition at line 67 of file application.cpp.

References m_configPathUser.

◆ setDefaults()

void mx::app::application::setDefaults	(	int	argc,
		char **	argv
	)

protectedvirtual

Set the default search paths for config files.

In general you should not need to redefine this.

The comand line arguments are not used by the default version, but are parameters in case derived classes need access when overriding.

Parameters

[in]	argc	standard command line result specifying number of arguments in argv
[in]	argv	standard command line result containing the arguments.

Definition at line 142 of file application.cpp.

References mx::sys::getEnv(), m_configPathCLBase, m_configPathCLBase_env, m_configPathGlobal, m_configPathGlobal_env, m_configPathLocal, m_configPathLocal_env, m_configPathUser, and m_configPathUser_env.

Referenced by setup().

◆ setup()

void mx::app::application::setup	(	int	argc,
		char **	argv
	)

protectedvirtual

Sets up the application by executing the configuration steps.

This is the key method which defines the mx::application configuration system. This will not normally need to be implemented by derived clasess – only do so if you intend to change the configuration process!

Parameters

[in]	argc	standard command line result specifying number of argumetns in argv
[in]	argv	standard command line result containing the arguments.

Definition at line 92 of file application.cpp.

References checkConfig(), config, invokedName, loadBasicConfig(), loadConfig(), loadStandardConfig(), loadStandardHelp(), m_configPathCL, m_configPathGlobal, m_configPathLocal, m_configPathUser, m_requireConfigPathLocal, mx::app::appConfigurator::parseCommandLine(), mx::app::appConfigurator::readConfig(), setDefaults(), setupBasicConfig(), setupConfig(), setupStandardConfig(), and setupStandardHelp().

Referenced by main().

◆ setupBasicConfig()

void mx::app::application::setupBasicConfig ( )

protectedvirtual

Setup a basic configuration. Can be used in an intermediate derived class to allow its children to use setupConfig.

This is called just before setupConfig().

Definition at line 211 of file application.cpp.

Referenced by setup().

◆ setupConfig()

void mx::app::application::setupConfig ( )

protectedvirtual

In derived classes this is where the config targets are added to config.

Definition at line 77 of file application.cpp.

Referenced by setup().

◆ setupStandardConfig()

void mx::app::application::setupStandardConfig ( )

protectedvirtual

Set up the command-line config option in a standard way.

This adds "-c --config" as command line options. You can override this function to change this behavior, or simply clear config at the beginning of setupConfig(). If you do this, you should also override loadStandardConfig().

Definition at line 190 of file application.cpp.

References mx::app::appConfigurator::add(), and config.

Referenced by setup().

◆ setupStandardHelp()

void mx::app::application::setupStandardHelp ( )

protectedvirtual

Set up the help an options in a standard way.

This adds "-h and --help" as command line options. You can override this function to change this behavior, or simply clear config at the beginning of setupConfig(). If you do this, you should also override loadStandardHelp().

Definition at line 195 of file application.cpp.

References mx::app::appConfigurator::add(), and config.

Referenced by setup().

Member Data Documentation

◆ config

appConfigurator mx::app::application::config

protected

The structure used for parsing and storing the configuration.

Definition at line 117 of file application.hpp.

Referenced by help(), loadStandardConfig(), loadStandardHelp(), main(), reReadConfig(), setup(), setupStandardConfig(), and setupStandardHelp().

◆ doHelp

bool mx::app::application::doHelp {false}

protected

Flag to control whether the help message is printed or not.

Definition at line 121 of file application.hpp.

Referenced by loadStandardHelp(), and main().

◆ invokedName

std::string mx::app::application::invokedName

protected

The name used to invoke this application.

Definition at line 102 of file application.hpp.

Referenced by help(), and setup().

◆ m_argc

int mx::app::application::m_argc

protected

Store argc for later use. E.g. in reReadConfig().

Definition at line 129 of file application.hpp.

Referenced by main(), and reReadConfig().

◆ m_argv

char** mx::app::application::m_argv

protected

Store argv for later use. E.g. in reReadConfig().

Definition at line 130 of file application.hpp.

Referenced by main(), and reReadConfig().

◆ m_configPathCL

std::string mx::app::application::m_configPathCL

protected

The path to a configuration file specified on the command line.

Definition at line 113 of file application.hpp.

Referenced by loadStandardConfig(), reReadConfig(), and setup().

◆ m_configPathCLBase

std::string mx::app::application::m_configPathCLBase

protected

A base path to add to the CL path. Set in constructor to use.

Definition at line 114 of file application.hpp.

Referenced by loadStandardConfig(), and setDefaults().

◆ m_configPathCLBase_env

std::string mx::app::application::m_configPathCLBase_env

protected

Environment variable to check for the CL base path. Set in constructor to use.

Definition at line 115 of file application.hpp.

Referenced by setDefaults().

◆ m_configPathGlobal

std::string mx::app::application::m_configPathGlobal

protected

The path to the gobal configuration file. Set in constructor to use.

Definition at line 104 of file application.hpp.

Referenced by reReadConfig(), setConfigPathGlobal(), setDefaults(), and setup().

◆ m_configPathGlobal_env

std::string mx::app::application::m_configPathGlobal_env

protected

Environment variable to check for the global config path. Set in constructor to use.

Definition at line 105 of file application.hpp.

Referenced by setDefaults().

◆ m_configPathLocal

std::string mx::app::application::m_configPathLocal

protected

The path to a local configuration file. Set in constructor to use.

Definition at line 108 of file application.hpp.

Referenced by reReadConfig(), setConfigPathLocal(), setDefaults(), and setup().

◆ m_configPathLocal_env

std::string mx::app::application::m_configPathLocal_env

protected

Environment variable to check for the local config path. Set in constructor to use.

Definition at line 109 of file application.hpp.

Referenced by setDefaults().

◆ m_configPathUser

std::string mx::app::application::m_configPathUser

protected

The path to the user's configuration file. If the first character is not '/' or '~', this is added to HOME. Set in constructor to use.

Definition at line 106 of file application.hpp.

Referenced by reReadConfig(), setConfigPathUser(), setDefaults(), and setup().

◆ m_configPathUser_env

std::string mx::app::application::m_configPathUser_env

protected

Environment variable to check fo the user config path. Set in constructor to use.

Definition at line 107 of file application.hpp.

Referenced by setDefaults().

◆ m_helpCFColWidth

int mx::app::application::m_helpCFColWidth {25}

protected

The width of the config file option column in the help message.

Definition at line 126 of file application.hpp.

Referenced by help().

◆ m_helpLOColWidth

int mx::app::application::m_helpLOColWidth {25}

protected

The width of the long option (–option) column in the help message.

Definition at line 125 of file application.hpp.

Referenced by help().

◆ m_helpSOColWidth

int mx::app::application::m_helpSOColWidth {2}

protected

The width of the short option (-o) column in the help message.

Definition at line 124 of file application.hpp.

Referenced by help().

◆ m_helpTypeColWidth

int mx::app::application::m_helpTypeColWidth {15}

protected

The width of the argument type column in the help message.

Definition at line 127 of file application.hpp.

Referenced by help().

◆ m_helpWidth

int mx::app::application::m_helpWidth {120}

protected

The total text width available for the help message.

Definition at line 123 of file application.hpp.

Referenced by help().

◆ m_preserveConfig

bool mx::app::application::m_preserveConfig {false}

protected

Flag controlling whether the configuration is cleared before execution. Set in derived constructor.

Definition at line 119 of file application.hpp.

Referenced by main().

◆ m_requireConfigPathLocal

bool mx::app::application::m_requireConfigPathLocal {true}

protected

Flag controlling whether lack of a local configuration file should be reported.

Definition at line 111 of file application.hpp.

Referenced by setup().

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

app/application.hpp
/home/jrmales/Source/mxlib/source/app/application.cpp

Public Member Functions

Protected Member Functions

Protected Attributes

Member Function Documentation

◆ checkConfig()

◆ execute()

◆ help()

◆ loadBasicConfig()

◆ loadConfig()

◆ loadStandardConfig()

◆ loadStandardHelp()

◆ main()

◆ optionHelp()

◆ reReadConfig()

◆ setConfigPathGlobal()

◆ setConfigPathLocal()

◆ setConfigPathUser()

◆ setDefaults()

◆ setup()

◆ setupBasicConfig()

◆ setupConfig()

◆ setupStandardConfig()

◆ setupStandardHelp()

Member Data Documentation

◆ config

◆ doHelp

◆ invokedName

◆ m_argc

◆ m_argv

◆ m_configPathCL

◆ m_configPathCLBase

◆ m_configPathCLBase_env

◆ m_configPathGlobal

◆ m_configPathGlobal_env

◆ m_configPathLocal

◆ m_configPathLocal_env

◆ m_configPathUser

◆ m_configPathUser_env

◆ m_helpCFColWidth

◆ m_helpLOColWidth

◆ m_helpSOColWidth

◆ m_helpTypeColWidth

◆ m_helpWidth

◆ m_preserveConfig

◆ m_requireConfigPathLocal