https://gitlab.opengeosys.org/ogs/ogs.git
Revision 96f6b540f209a25ee84a24bf7b6d2309b0efc445 authored by Dmitri Naumov on 31 January 2023, 10:36:02 UTC, committed by Dmitri Naumov on 01 February 2023, 14:23:26 UTC
1 parent 3fb75b9
Tip revision: 96f6b540f209a25ee84a24bf7b6d2309b0efc445 authored by Dmitri Naumov on 31 January 2023, 10:36:02 UTC
[PL/CT] Change assertion to OGS_FATAL
[PL/CT] Change assertion to OGS_FATAL
Tip revision: 96f6b54
ConfigTree.h
/**
* \file
* \copyright
* Copyright (c) 2012-2023, OpenGeoSys Community (http://www.opengeosys.org)
* Distributed under a Modified BSD License.
* See accompanying file LICENSE.txt or
* http://www.opengeosys.org/project/license
*
*/
#pragma once
#include <boost/property_tree/ptree.hpp>
#include <functional>
#include <iosfwd>
#include <iterator>
#include <map>
#include <memory>
#include <optional>
#include <typeindex>
#include <utility>
#include <vector>
extern template class boost::property_tree::basic_ptree<
std::string, std::string, std::less<>>;
namespace BaseLib
{
class ConfigTree;
/*! Check if \c conf has been read entirely and invalidate it.
*
* This method can safely be called on \c nullptr's.
*
* \see ConfigTree::checkAndInvalidate()
*/
void checkAndInvalidate(ConfigTree* const conf);
//! \overload
void checkAndInvalidate(std::unique_ptr<ConfigTree> const& conf);
//! \overload
void checkAndInvalidate(ConfigTree& conf);
template <typename Iterator>
class Range;
/*!
* Wrapper around a Boost Property Tree with some basic error reporting
* features.
*
* Features. This class:
* * makes sure that every configuration setting in a Property Tree is read
* exactly once. If some settings is not read (e.g. due to a typo), a warning
* message is generated. The message contains a hint where it occurred.
* * enforces a naming scheme of settings: letters a-z, numbers 0-9, underscore
* * provides some functionality to read lists of values using range-based for
* loops.
* * has rather long method names that are easily greppable from the source
* code. So a list of supported configuration options can be easily obtained
* from the source code.
*
* The purpose of this class is to reduce or completely avoid the amount of
* error-handling code in routines that take configuration parameters.
*
* Most methods of this class check that they have not been called before for
* the same \c ConfigTree and the same parameter. This behaviour helps to
* enforce that every parameter is read exactly once during parsing of the
* configuration settings.
*
* The most notable restriction of this class when compared to plain tree
* traversal is, that one must know all the XML tags (i.e. configuration
* parameters) at compile time. It is not possible to read from this class,
* which configuration parameters are present in the tree. This restriction,
* however, is intended, because it provides the possibility to get all existing
* configuration parameters from the source code.
*
* This class maintains a read counter for each parameter accessed through any
* of its methods. Read counters are increased with every read (the only
* exception being the peekConfigParameter() method). The destructor finally
* decreases the read counter for every tag/attribute it find on the current
* level of the XML tree. If the increases/decreases don't cancel each other,
* warning messages are generated. This check can also be enforced before
* destruction by using the BaseLib::checkAndInvalidate() functions.
*
* The design of this class entails some limitations compared to traversing a
* plain tree, e.g., it is not possible to obtain a list of tags or attributes
* from the tree, but one has to explicitly query the specific tags/attributes
* one is interested in. That way it is possible to get all used configuration
* parameters directly from the source code where this class is used, and to
* maintain the quality of the configuration parameter documentation.
*
* Instances of this class only keep a reference to the underlying
* <tt>boost::property_tree</tt>. Therefore it is necessary that the underlying
* property tree stays intact as long as any instance---i.e. the top level
* ConfigTree and any of its children---reference it. In order to simplify the
* handling of this dependence, the class ConfigTreeTopLevel can be used.
*
* The construction of a ConfigTree from the content of an XML file can be done
* with the function BaseLib::makeConfigTree(), which performs many error
* checks. For limitations of the used XML parser, please have a look at that
* function's documentation.
*/
class ConfigTree final
{
public:
/*! A wrapper around a Boost Iterator for iterating over ranges of subtrees.
*
* The methods of this class tell the associated (parent) \c ConfigTree
* object when a setting has been parsed.
*/
class SubtreeIterator
{
public:
using iterator_category = std::input_iterator_tag;
using value_type = ConfigTree;
using difference_type = std::ptrdiff_t;
using pointer = ConfigTree*;
using reference = ConfigTree&;
using Iterator = boost::property_tree::ptree::const_assoc_iterator;
explicit SubtreeIterator(Iterator const& it, std::string const& root,
ConfigTree const& parent)
: it_(it), tagname_(root), parent_(parent)
{
}
SubtreeIterator& operator++()
{
++it_;
has_incremented_ = true;
return *this;
}
ConfigTree operator*()
{
// if this iterator has been incremented since the last dereference,
// tell the parent_ instance that a subtree now has been parsed.
if (has_incremented_)
{
has_incremented_ = false;
parent_.markVisited(tagname_, Attr::TAG, false);
}
return ConfigTree(it_->second, parent_, tagname_);
}
bool operator==(SubtreeIterator const& other) const
{
return it_ == other.it_;
}
bool operator!=(SubtreeIterator const& other) const
{
return it_ != other.it_;
}
private:
bool has_incremented_ = true;
Iterator it_;
protected:
std::string const tagname_;
ConfigTree const& parent_;
};
/*! A wrapper around a Boost Iterator for iterating over ranges of
* parameters.
*
* The methods of this class tell the associated (parent) \c ConfigTree
* object when a setting has been parsed.
*/
class ParameterIterator : public SubtreeIterator
{
public:
//! Inherit the constructor
using SubtreeIterator::SubtreeIterator;
ConfigTree operator*()
{
auto st = SubtreeIterator::operator*();
if (st.hasChildren())
{
parent_.error("The requested parameter <" + tagname_ +
"> has child elements.");
}
return st;
}
};
/*!
* A wrapper around a Boost Iterator for iterating over ranges of values.
*
* The methods of this class tell the associated (parent) \c ConfigTree
* object when a setting has been parsed.
*/
template <typename ValueType>
class ValueIterator
{
public:
using iterator_category = std::input_iterator_tag;
using value_type = ConfigTree;
using difference_type = std::ptrdiff_t;
using pointer = ConfigTree*;
using reference = ConfigTree&;
using Iterator = boost::property_tree::ptree::const_assoc_iterator;
explicit ValueIterator(Iterator const& it, std::string const& root,
ConfigTree const& parent)
: it_(it), tagname_(root), parent_(parent)
{
}
ValueIterator<ValueType>& operator++()
{
++it_;
has_incremented_ = true;
return *this;
}
ValueType operator*()
{
// if this iterator has been incremented since the last dereference,
// tell the parent_ instance that a setting now has been parsed.
if (has_incremented_)
{
has_incremented_ = false;
parent_.markVisited<ValueType>(tagname_, Attr::TAG, false);
}
return ConfigTree(it_->second, parent_, tagname_)
.getValue<ValueType>();
}
bool operator==(ValueIterator<ValueType> const& other) const
{
return it_ == other.it_;
}
bool operator!=(ValueIterator<ValueType> const& other) const
{
return it_ != other.it_;
}
private:
bool has_incremented_ = true;
Iterator it_;
std::string const tagname_;
ConfigTree const& parent_;
};
//! The tree being wrapped by this class.
using PTree = boost::property_tree::ptree;
/*! Type of the function objects used as callbacks.
*
* Arguments of the callback:
* \arg \c filename the file being from which this ConfigTree has been read.
* \arg \c path the path in the tree where the message was generated.
* \arg \c message the message to be printed.
*/
using Callback = std::function<void(const std::string& filename,
const std::string& path,
const std::string& message)>;
/*!
* Creates a new instance wrapping the given Boost Property Tree.
*
* \param top_level_tree the top level Boost Property Tree
* \param filename the file from which the \c tree has been read
* \param error_cb callback function to be called on error.
* \param warning_cb callback function to be called on warning.
*
* The callback functions must be valid callable functions, i.e. not
* nullptr's. They are configurable in order to make unit tests of this
* class easier. They should not be provided in production code!
*
* Defaults are strict: By default, both callbacks are set to the same
* function, i.e., warnings will also result in program abortion!
*/
explicit ConfigTree(PTree&& top_level_tree,
std::string filename,
Callback error_cb,
Callback warning_cb);
//! copying is not compatible with the semantics of this class
ConfigTree(ConfigTree const&) = delete;
//! After being moved from, \c other is in an undefined state and must not
//! be used anymore!
ConfigTree(ConfigTree&& other);
//! copying is not compatible with the semantics of this class
ConfigTree& operator=(ConfigTree const&) = delete;
//! After being moved from, \c other is in an undefined state and must not
//! be used anymore!
ConfigTree& operator=(ConfigTree&& other);
//! Used to get the project file name.
std::string const& getProjectFileName() const { return filename_; }
/*! \name Methods for directly accessing parameter values
*
*/
//!\{
/*! Get parameter \c param of type \c T from the configuration tree.
*
* \return the value looked for.
*
* \pre \c param must not have been read before from this ConfigTree.
*/
template <typename T>
T getConfigParameter(std::string const& param) const;
/*! Get parameter \c param of type \c T from the configuration tree or the
* \c default_value.
*
* This method has a similar behaviour as getConfigParameter(std::string
* const&) except the \c default_value is returned if the attribute has not
* been found.
*
* \pre \c param must not have been read before from this ConfigTree.
*/
template <typename T>
T getConfigParameter(std::string const& param,
T const& default_value) const;
/*! Get parameter \c param of type \c T from the configuration tree if
* present
*
* This method has a similar behaviour as getConfigParameter(std::string
* const&) except no errors are raised. Rather it can be told from the
* return value if the parameter could be read.
*
* \pre \c param must not have been read before from this ConfigTree.
*/
template <typename T>
std::optional<T> getConfigParameterOptional(std::string const& param) const;
/*! Fetches all parameters with name \c param from the current level of the
* tree.
*
* The return value is suitable to be used with range-base for-loops.
*
* \pre \c param must not have been read before from this ConfigTree.
*/
template <typename T>
Range<ValueIterator<T>> getConfigParameterList(
std::string const& param) const;
//!\}
/*! \name Methods for accessing parameters that have attributes
*
* The <tt>getConfigParameter...()</tt> methods in this group---note: they
* do not have template parameters---check that the queried parameters do
* not have any children (apart from XML attributes); if they do, error() is
* called.
*
* The support for parameters with attributes is limited in the sense that
* it is not possible to peek/check them. However, such functionality can
* easily be added on demand.
*/
//!\{
/*! Get parameter \c param from the configuration tree.
*
* \return the subtree representing the requested parameter
*
* \pre \c param must not have been read before from this ConfigTree.
*/
ConfigTree getConfigParameter(std::string const& root) const;
/*! Get parameter \c param from the configuration tree if present.
*
* \return the subtree representing the requested parameter
*
* \pre \c param must not have been read before from this ConfigTree.
*/
std::optional<ConfigTree> getConfigParameterOptional(
std::string const& root) const;
/*! Fetches all parameters with name \c param from the current level of the
* tree.
*
* The return value is suitable to be used with range-base for-loops.
*
* \pre \c param must not have been read before from this ConfigTree.
*/
Range<ParameterIterator> getConfigParameterList(
std::string const& param) const;
/*! Get the plain data contained in the current level of the tree.
*
* \return the data converted to the type \c T
*
* \pre The data must not have been read before.
*/
template <typename T>
T getValue() const;
/*! Get XML attribute \c attr of type \c T for the current parameter.
*
* \return the requested attribute's value.
*
* \pre \c attr must not have been read before from the current parameter.
*/
template <typename T>
T getConfigAttribute(std::string const& attr) const;
/*! Get XML attribute \c attr of type \c T for the current parameter or the
* \c default_value.
*
* This method has a similar behaviour as getConfigAttribute(std::string
* const&) except the \c default_value is returned if the attribute has not
* been found.
*
* \return the requested attribute's value.
*
* \pre \c attr must not have been read before from the current parameter.
*/
template <typename T>
T getConfigAttribute(std::string const& attr, T const& default_value) const;
/*! Get XML attribute \c attr of type \c T for the current parameter if
* present.
*
* \return the requested attribute's value.
*
* \pre \c attr must not have been read before from the current parameter.
*/
template <typename T>
std::optional<T> getConfigAttributeOptional(std::string const& attr) const;
//!\}
/*! \name Methods for peeking and checking parameters
*
* To be used in builder/factory functions: E.g., one can peek a parameter
* denoting the type of an object to generate in the builder, and check the
* type parameter in the constructor of the generated object.
*/
//!\{
/*! Peek at a parameter \c param of type \c T from the configuration tree.
*
* This method is an exception to the single-read rule. It is meant to be
* used to tell from a ConfigTree instance where to pass that instance on
* for further processing.
*
* But in order that the requested parameter counts as "completely parsed",
* it has to be read through some other method, too.
*
* Return value and error behaviour are the same as for
* getConfigParameter<T>(std::string const&).
*/
template <typename T>
T peekConfigParameter(std::string const& param) const;
/*! Assert that \c param has the given \c value.
*
* Convenience method combining getConfigParameter(std::string const&) with
* a check.
*/
template <typename T>
void checkConfigParameter(std::string const& param, T const& value) const;
//! Make checkConfigParameter() work for string literals.
template <typename Ch>
void checkConfigParameter(std::string const& param, Ch const* value) const;
//!\}
/*! \name Methods for accessing subtrees
*/
//!\{
/*! Get the subtree rooted at \c root
*
* If \c root is not found error() is called.
*
* \pre \c root must not have been read before from this ConfigTree.
*/
ConfigTree getConfigSubtree(std::string const& root) const;
/*! Get the subtree rooted at \c root if present
*
* \pre \c root must not have been read before from this ConfigTree.
*/
std::optional<ConfigTree> getConfigSubtreeOptional(
std::string const& root) const;
/*! Get all subtrees that have a root \c root from the current level of the
* tree.
*
* The return value is suitable to be used with range-base for-loops.
*
* \pre \c root must not have been read before from this ConfigTree.
*/
Range<SubtreeIterator> getConfigSubtreeList(std::string const& root) const;
//!\}
/*! \name Methods for ignoring parameters
*/
//!\{
/*! Tell this instance to ignore parameter \c param.
*
* This method is used to avoid warning messages.
*
* \pre \c param must not have been read before from this ConfigTree.
*/
void ignoreConfigParameter(std::string const& param) const;
/*! Tell this instance to ignore all parameters \c param on the current
* level of the tree.
*
* This method is used to avoid warning messages.
*
* \pre \c param must not have been read before from this ConfigTree.
*/
void ignoreConfigParameterAll(std::string const& param) const;
/*! Tell this instance to ignore the XML attribute \c attr.
*
* This method is used to avoid warning messages.
*
* \pre \c attr must not have been read before from this ConfigTree.
*/
void ignoreConfigAttribute(std::string const& attr) const;
//!\}
//! The destructor performs the check if all nodes at the current level of
//! the tree have been read. Errors raised by the check are swallowed. Use
//! assertNoSwallowedErrors() manually to check for those.
~ConfigTree();
//! Default error callback function
//! Will throw std::runtime_error
static void onerror(std::string const& filename, std::string const& path,
std::string const& message);
//! Default warning callback function
//! Will print a warning message
static void onwarning(std::string const& filename, std::string const& path,
std::string const& message);
//! Asserts that there have not been any errors reported in the destructor.
static void assertNoSwallowedErrors();
private:
//! Default implementation of reading a value of type T.
template <typename T>
std::optional<T> getConfigParameterOptionalImpl(std::string const& param,
T* /*unused*/) const;
//! Implementation of reading a vector of values of type T.
template <typename T>
std::optional<std::vector<T>> getConfigParameterOptionalImpl(
std::string const& param, std::vector<T>* /*unused*/) const;
struct CountType
{
int count;
std::type_index type;
};
//! Used to indicate if dealing with XML tags or XML attributes
enum class Attr : bool
{
TAG = false,
ATTR = true
};
//! Used for wrapping a subtree
explicit ConfigTree(PTree const& tree, ConfigTree const& parent,
std::string const& root);
/*! Called if an error occurs. Will call the error callback.
*
* This method only acts as a helper method and throws std::runtime_error.
*/
[[noreturn]] void error(std::string const& message) const;
//! Called for printing warning messages. Will call the warning callback.
//! This method only acts as a helper method.
void warning(std::string const& message) const;
//! Checks if \c key complies with the rules [a-z0-9_].
void checkKeyname(std::string const& key) const;
//! Used to generate the path of a subtree.
std::string joinPaths(std::string const& p1, std::string const& p2) const;
//! Asserts that the \c key has not been read yet.
void checkUnique(std::string const& key) const;
//! Asserts that the attribute \c attr has not been read yet.
void checkUniqueAttr(std::string const& attr) const;
/*! Keeps track of the key \c key and its value type \c T.
*
* This method asserts that a key is read always with the same type.
*
* \c param peek_only if true, do not change the read-count of the given
* key.
*/
template <typename T>
CountType& markVisited(std::string const& key, Attr const is_attr,
bool peek_only) const;
/*! Keeps track of the key \c key and its value type ConfigTree.
*
* This method asserts that a key is read always with the same type.
*
* \c param peek_only if true, do not change the read-count of the given
* key.
*/
CountType& markVisited(std::string const& key, Attr const is_attr,
bool const peek_only) const;
//! Used in the destructor to compute the difference between number of reads
//! of a parameter and the number of times it exists in the ConfigTree
void markVisitedDecrement(Attr const is_attr, std::string const& key) const;
//! Checks if this tree has any children.
bool hasChildren() const;
/*! Checks if the top level of this tree has been read entirely (and not too
* often).
*
* \post This method also invalidates the instance, i.e., afterwards it must
* not be used anymore!
*/
void checkAndInvalidate();
//! returns a short string at suitable for error/warning messages
static std::string shortString(std::string const& s);
//! Root of the tree.
//!
//! Owned by all ConfigTree instances that might access any part of it.
std::shared_ptr<PTree const> top_level_tree_;
//! The wrapped tree.
PTree const* tree_;
//! A path printed in error/warning messages.
std::string path_;
//! The path of the file from which this tree has been read.
std::string filename_;
//! A pair (is attribute, tag/attribute name).
using KeyType = std::pair<Attr, std::string>;
//! A map KeyType -> (count, type) keeping track which parameters have been
//! read how often and which datatype they have.
//!
//! This member will be written to when reading from the config tree.
//! Therefore it has to be mutable in order to be able to read from
//! constant instances, e.g., those passed as constant references to
//! temporaries.
mutable std::map<KeyType, CountType> visited_params_;
//! Indicates if the plain data contained in this tree has already been
//! read.
mutable bool have_read_data_ = false;
Callback onerror_; //!< Custom error callback.
Callback onwarning_; //!< Custom warning callback.
//! Character separating two path components.
static const char pathseparator;
//! Set of allowed characters as the first letter of a key name.
static const std::string key_chars_start;
//! Set of allowed characters in a key name.
static const std::string key_chars;
friend void checkAndInvalidate(ConfigTree* const conf);
friend void checkAndInvalidate(ConfigTree& conf);
friend void checkAndInvalidate(std::unique_ptr<ConfigTree> const& conf);
};
} // namespace BaseLib
#include "ConfigTree-impl.h" // IWYU pragma: keep
![swh spinner](/static/img/swh-spinner.gif)
Computing file changes ...