/**
 * @file Common/iconfig.h
 * @brief eVaf configuration interface
 * @author Enar Vaikene
 *
 * Copyright (c) 2011-2019 Enar Vaikene
 *
 * This file is part of the eVaf C++ cross-platform application development framework.
 *
 * This file can be used under the terms of the GNU General Public License
 * version 3.0 as published by the Free Software Foundation and appearing in
 * the file LICENSE included in the packaging of this file. Please review the
 * the following information to ensure the GNU General Public License version
 * 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
 *
 * Alternatively, this file may be used in accordance with the Commercial License
 * Agreement provided with the Software.
 */

#ifndef __COMMON_ICONFIG_H
#  define __COMMON_ICONFIG_H

#include "libcommon.h"

#include <QObject>
#include <QString>
#include <QVariant>

namespace eVaf {
namespace Common {

/**
 * eVaf configuration interface.
 * @code#include <iConfig>@endcode
 *
 * The iConfig interface provides access to configuration parameters. Methods in this interface can be
 * used to read and write configuration parameters.
 *
 * The default implementation of the iConfig interface uses INI files in the eVaf::Common::iApp::etcDir()
 * directory. Additional configuration backends can be provided by re-implementing the interface.
 *
 * Configuration parameters are identified by a name in the following format:
 * @verbatim [<backend:>][<file>]/<section>/<key> @endverbatim
 *
 * Where:
 * @li \<backend:\> is an optional identifier for the configuration backend. This part is ignored by the default
 * iConfig interface implementation and is reserved for custom modules. For example, a custom module could look
 * for the 'db:' backend identifier and store parameters in a database. Any other requests would be forwarded to
 * the default implementation.
 * @li \<file\> is an optional configuration file name. The default iConfig interface implementation uses the file
 * name part to locate the INI file in the eVaf::Common::iApp::etcDir() directory. If the file name part
 * is '*' or empty, uses eVaf::Common::iApp::name() for the file name.
 * @li \<section\> is the name of the section. Section names can contain extra '/' characters to build a structured
 * tree of configuration sections.
 * @li \<key\> is the name of the parameter.
 *
 * For example:
 * @li 'db:local/extensions/help/module' - backend 'db:', file or database name 'local', section name 'extensions/help' and
 * the key 'module';
 * @li '/extensions/help/module' - default backend, default file name, section name 'extensions/help' and the key 'module'.
 */
class COMMON_EXPORT iConfig : public QObject
{
    Q_OBJECT

public:

    /// Interface constructor
    iConfig() : QObject() {}

    /// Empty virtual destructor
    virtual ~iConfig() {}

    /**
     * Returns the current iConfig interface instance
     * @return The iConfig interface
     *
     * This method returns the current iConfig interface instance as shown in the following example:
     * @code
     * QString moduleName =
     *     eVaf::Common::iConfig::instance()->getValue("/extensions/help/module", "libHelp.so").toString();
     * @endcode
     */
    static iConfig * instance();

    /**
     * Reads a configuration parameter value
     * @param paramName Name of the parameter
     * @param defaultValue Default value
     * @return The parameter value or the default value if the parameter cannot be found
     *
     * The getValue() method returns a configuration parameter value identified by the parameter name. If the parameter
     * cannot be read or is not found, returns the default value.
     *
     * The default value is used to determine the type of the value. For example, if the default value is an integer, then
     * the returned value is also an integer. The default iConfig interface implementation validates parameter values and
     * makes sure that the parameter value is of the proper type. If the value cannot be converted to the proper type,
     * returns the default value. Other implementations of the iConfig interface are encouraged to do the same.
     */
    virtual QVariant getValue(QString const & paramName, QVariant const & defaultValue) const = 0;

    /**
     * Writes a configuration parameter value
     * @param paramName Name of the parameter
     * @param value The parameter value
     * @param commit If true, then commits new parameter values
     * @return True if succeeded; false if not
     *
     * The setValue() method writes new configuration parameter values identified by the parameter name.
     *
     * The commit argument can be used to improve the performance of writing several parameter values at once. Use
     * commit = false for all except the last parameter's write operation.
     * @code
     * iConfig * conf = eVaf::Common::iConfig::instance();
     * conf->setValue("/main/param1", 1, false);
     * conf->setValue("/main/param2", 2, false);
     * conf->setValue("/main/param3", 3); // Last parameter in the block
     * @endcode
     */
    virtual bool setValue(QString const & paramName, QVariant const & value, bool commit = true) = 0;

};


} // namespace eVaf::Common
} // namespace eVaf

#endif // iconfig.h