application.hpp

Go to the documentation of this file.

/** \file application.hpp
 * \author Jared R. Males
 * \brief A class for managing application configuration and execution
 *
 */
 
//***********************************************************************//
// Copyright 2015, 2016, 2017, 2018 Jared R. Males (jaredmales@gmail.com)
//
// This file is part of mxlib.
//
// mxlib is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// mxlib is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with mxlib.  If not, see <http://www.gnu.org/licenses/>.
//***********************************************************************//
 
#ifndef app_application_hpp
#define app_application_hpp
 
#include "appConfigurator.hpp"
#include "../ioutils/textTable.hpp"
 
namespace mx
{
namespace app
{
 
/// A class for managing application configuration and execution
/** Derived classes should implement at a minimum
  *
  * \code
    virtual void setupConfig();
    virtual void loadConfig();
    virtual int execute();
   \endcode
  *
  * These are executed in the order shown by the call to \ref 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  \ref appConfigurator named `config`.
  * For specification of the configuration file syntax and command line arguments see \ref appConfigurator.
  *
  * The configuration should be set up in the \ref setupConfig function.  This is normally done using
  * the appConfigurator::add method, as in:
  * \code
    void derived_class::setupConfig()
    {
       config.add("name", "s", "long", argType::Required, "section", "keyword", false, "int", "help message");
    }
    \endcode
  * The configuration is then accessed using the `config` member's operator as in
  \code
    void derived_class::loadConfig()
    {
         int val = 0;
         config(val, "name");
    }
  \endcode
  * 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
  \verbatim
  [section]
  keyword=2
  \endverbatim
  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 \ref 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 \ref help method.
  *
  * \ingroup mxApp
  */
class application
{
 
  protected:
    std::string invokedName; ///< The name used to invoke this application.
 
    std::string m_configPathGlobal;     ///< The path to the gobal configuration file.  Set in constructor to use.
    std::string m_configPathGlobal_env; ///< Environment variable to check for the global config path.  Set in
                                        ///< constructor to use.
    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.
    std::string
        m_configPathUser_env; ///< Environment variable to check fo the user config path.  Set in constructor to use.
    std::string m_configPathLocal; ///< The path to a local configuration file. Set in constructor to use.
    std::string
        m_configPathLocal_env; ///< Environment variable to check for the local config path.  Set in constructor to use.
 
    bool m_requireConfigPathGlobal{
        true }; ///< Flag controlling whether lack of a global configuration file should be reported.
    bool m_requireConfigPathUser{
        true }; ///< Flag controlling whether lack of a user configuration file should be reported.
    bool m_requireConfigPathLocal{
        true }; ///< Flag controlling whether lack of a local configuration file should be reported.
 
    std::string m_configPathCL;     ///< The path to a configuration file specified on the command line.
    std::string m_configPathCLBase; ///< A base path to add to the CL path.  Set in constructor to use.
    std::string
        m_configPathCLBase_env; ///< Environment variable to check for the CL base path.  Set in constructor to use.
 
    appConfigurator config; ///< The structure used for parsing and storing the configuration.
 
    bool m_preserveConfig{ false }; ///< Flag controlling whether the configuration is cleared before execution.  Set in
                                    ///< derived constructor.
 
    bool doHelp{ false }; /**< Flag to control whether the help message is printed or not.
                                 If true, it is printed and the app exits */
 
    bool m_configOnly {false}; /**< Flag to set if application should exit after loading the configuration. This
                                    could be used to have a config validation mode.*/
 
    int m_helpWidth{ 120 };       ///< The total text width available for the help message.
    int m_helpSOColWidth{ 2 };    ///< The width of the short option (-o) column in the help message.
    int m_helpLOColWidth{ 25 };   ///< The width of the long option (--option) column in the help message.
    int m_helpCFColWidth{ 25 };   ///< The width of the config file option column in the help message.
    int m_helpTypeColWidth{ 15 }; ///< The width of the argument type column in the help message.
 
    std::string m_nonOptionHelp; ///< String to print to describe non-option arguments.
 
    int m_argc;    ///< Store argc for later use. E.g. in reReadConfig().
    char **m_argv; ///< Store argv for later use. E.g. in reReadConfig().
 
  public:
    // application();
 
    virtual ~application();
 
    /// The application main function.
    /** Call this from the true main function, passing the command line arguments to be processed.
     * This calls \ref setup(), then checks if the m_doHelp flag was set.  If so, it calls \ref help() and returns.
     * If m_doHelp is not set, it then clears the config structure, and then calls \ref execute().
     *
     * The configuration is cleared before the call to execute, unless m_preserveConfig = true.
     *
     * \returns 1 if help is executed.
     * \returns -1 on error.
     * \returns the value of \ref execute() otherwise.
     */
    int main( int argc,   ///< [in] standard command line result specifying number of arguments in argv
              char **argv ///< [in] standard command line result containing the arguments.
    );
 
    /// Set the global configuration path
    void setConfigPathGlobal( const std::string &s /**< [in] the new path */ );
 
    /// 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.
     */
    void setConfigPathUser( const std::string &s /**< [in] the new path to the user config file*/ );
 
    /// Set the local configuration path
    void setConfigPathLocal( const std::string &s /**< [in] the new path */ );
 
  protected:
    /** \name Required Overrides
     * These methods should be implemented in derived classes to use an mx::application in its default behavior.
     * @{
     */
 
    /// In derived classes this is where the config targets are added to \ref config.
    virtual void setupConfig();
 
    /// Override this function to extract the configured values and set up the application.
    virtual void loadConfig();
 
    /// This function is where the derived class should do its work.
    /** The application will exit with the return value of execute.
     */
    virtual int execute();
 
    ///@}
 
    /** \name Optional Overrides
     * These methods do not need to be implemented in derived classes unless it is desired to change behavior.
     * @{
     */
 
    /// 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!
     */
    virtual void setup( int argc,   ///< [in] standard command line result specifying number of arguments in argv
                        char **argv ///< [in] standard command line result containing the arguments.
    );
 
    /// 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.
     * \returns -1 on error.
     */
    int reReadConfig();
 
    /// 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.
     *
     */
    virtual void setDefaults( int argc,   ///< [in] standard command line result specifying number of arguments in argv
                              char **argv ///< [in] standard command line result containing the arguments.
    );
 
    /// 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 \ref setupConfig().  If you do this, you should also override \ref loadStandardConfig().
     */
    virtual void setupStandardConfig();
 
    /// 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 \ref setupConfig().  If you do this, you should also override \ref loadStandardHelp().
     */
    virtual void setupStandardHelp();
 
    /// Loads the values of "config".
    /** Override this function if you do not want to use this, or have different behavior.
     * See also \ref setupStandardConfig().
     */
    virtual void loadStandardConfig();
 
    /// Loads the value of "help" into m_doHelp.
    /** Override this function if you do not want to use this, or have different behavior.
     * See also \ref setupStandardConfig().
     */
    virtual void loadStandardHelp();
 
    /// Format a configTarget for the help message.
    virtual void optionHelp( configTarget &tgt,     ///< [in] The Target
                             ioutils::textTable &tt ///< [out] the textTable being populated
    );
 
    /// 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().
     */
    virtual void setupBasicConfig();
 
    /// 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().
     */
    virtual void loadBasicConfig();
 
    /// 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 m_doHelp flag.
     */
    virtual void checkConfig();
 
    /// Print a formatted help message, based on the config target inputs.
    virtual void help();
 
    ///@}
};
 
} // namespace app
} // namespace mx
 
#endif // app_application_hpp
 
// Deprecations:
//  Produce errors if older code is compiled which attempts to define-config the config:
 
#ifdef MX_APP_DEFAULT_configPathGlobal
#error MX_APP_DEFAULT_configPathGlobal no longer works.  Set m_configPathGlobal in constructor.
#endif
 
#ifdef MX_APP_DEFAULT_configPathGlobal_env
#error MX_APP_DEFAULT_configPathGlobal_env no longer works.  Set m_configPathGlobal_env in constructor.
#endif
 
#ifdef MX_APP_DEFAULT_configPathUser
#error MX_APP_DEFAULT_configPathUser no longer works.  Set m_configPathUser in constructor.
#endif
 
#ifdef MX_APP_DEFAULT_configPathUser_env
#error MX_APP_DEFAULT_configPathUser_env no longer works.  Set m_configPathUser_env in constructor.
#endif
 
#ifdef MX_APP_DEFAULT_configPathLocal
#error MX_APP_DEFAULT_configPathLocal no longer works.  Set m_configPathLocal in constructor.
#endif
 
#ifdef MX_APP_DEFAULT_configPathLocal_env
#error MX_APP_DEFAULT_configPathLocal_env no longer works.  Set m_configPathLocal_env in constructor.
#endif
 
#ifdef MX_APP_DEFAULT_configPathCLBase_env
#error MX_APP_DEFAULT_configPathCLBase_env no longer works.  Set m_configPathCLBase_env in constructor.
#endif