Detailed Description

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 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 boost::property_tree. 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.

Definition at line 100 of file ConfigTree.h.

#include <ConfigTree.h>

Classes
class	Child
struct	CountType
class	ParameterIterator
class	SubtreeIterator
class	ValueIterator

Public Types
using	PTree = boost::property_tree::ptree
	The tree being wrapped by this class.
using	Callback

Public Member Functions
	ConfigTree (PTree &&top_level_tree, std::string filename, Callback error_cb, Callback warning_cb)
	ConfigTree (ConfigTree const &)=delete
	copying is not compatible with the semantics of this class
	ConfigTree (ConfigTree &&other)
ConfigTree &	operator= (ConfigTree const &)=delete
	copying is not compatible with the semantics of this class
ConfigTree &	operator= (ConfigTree &&other)
std::filesystem::path const &	projectFilePath () const
	Used to get the project file name.
std::filesystem::path	projectDirectory () const
	~ConfigTree ()
Methods for directly accessing parameter values
template<typename T>
T	getConfigParameter (std::string const &param) const
template<typename T>
T	getConfigParameter (std::string const &param, T const &default_value) const
template<typename T>
std::optional< T >	getConfigParameterOptional (std::string const &param) const
template<typename T>
Range< ValueIterator< T > >	getConfigParameterList (std::string const &param) const
Methods for accessing parameters that have attributes
The getConfigParameter...() 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.
ConfigTree	getConfigParameter (std::string const &param) const
std::optional< ConfigTree >	getConfigParameterOptional (std::string const &param) const
Range< ParameterIterator >	getConfigParameterList (std::string const &param) const
template<typename T>
T	getValue () const
template<typename T>
T	getConfigAttribute (std::string const &attr) const
template<typename T>
T	getConfigAttribute (std::string const &attr, T const &default_value) const
template<typename T>
std::optional< T >	getConfigAttributeOptional (std::string const &attr) const
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.
template<typename T>
T	peekConfigParameter (std::string const &param) const
void	checkConfigParameter (std::string const &param, std::string_view const value) const
Methods for ignoring parameters
void	ignoreConfigParameter (std::string const &param) const
void	ignoreConfigParameterAll (std::string const &param) const
void	ignoreConfigAttribute (std::string const &attr) const

Static Public Member Functions
static void	onerror (std::string const &filename, std::string const &path, std::string const &message)
static void	onwarning (std::string const &filename, std::string const &path, std::string const &message)
static void	assertNoSwallowedErrors ()
	Asserts that there have not been any errors reported in the destructor.

Private Types
enum class	Attr : bool { TAG = false , ATTR = true }
	Used to indicate if dealing with XML tags or XML attributes. More...
using	KeyType = std::pair<Attr, std::string>
	A pair (is attribute, tag/attribute name).

Private Member Functions
template<typename T>
std::optional< T >	getConfigParameterOptionalImpl (std::string const &param, T *) const
	Default implementation of reading a value of type T.
template<typename T>
std::optional< std::vector< T > >	getConfigParameterOptionalImpl (std::string const &param, std::vector< T > *) const
	Implementation of reading a vector of values of type T.
	ConfigTree (PTree const &tree, ConfigTree const &parent, std::string const &root)
	Used for wrapping a subtree.
void	error (std::string const &message) const
void	warning (std::string const &message) const
void	checkKeyname (std::string const &key) const
	Checks if `key` complies with the rules [a-z0-9_].
std::string	joinPaths (std::string const &p1, std::string const &p2) const
	Used to generate the path of a subtree.
void	checkUnique (std::string const &key) const
	Asserts that the `key` has not been read yet.
void	checkUniqueAttr (std::string const &attr) const
	Asserts that the attribute `attr` has not been read yet.
template<typename T>
CountType &	markVisited (std::string const &key, Attr const is_attr, bool peek_only) const
CountType &	markVisited (std::string const &key, Attr const is_attr, bool const peek_only) const
void	markVisitedDecrement (Attr const is_attr, std::string const &key) const
bool	hasChildren () const
	Checks if this tree has any children.
void	checkAndInvalidate ()

Static Private Member Functions
static std::string	shortString (std::string const &s)
	returns a short string at suitable for error/warning messages

Private Attributes
std::shared_ptr< PTree const >	top_level_tree_
PTree const *	tree_
	The wrapped tree.
std::string	path_
	A path printed in error/warning messages.
std::filesystem::path	filepath_
	The path of the file from which this tree has been read.
std::map< KeyType, CountType >	visited_params_
bool	have_read_data_ = false
Callback	onerror_
	Custom error callback.
Callback	onwarning_
	Custom warning callback.

Static Private Attributes
static const char	pathseparator = '/'
	Character separating two path components.
static const std::string	key_chars_start = "abcdefghijklmnopqrstuvwxyz"
	Set of allowed characters as the first letter of a key name.
static const std::string	key_chars = key_chars_start + "_0123456789"
	Set of allowed characters in a key name.

Friends
void	checkAndInvalidate (ConfigTree *const conf)
void	checkAndInvalidate (ConfigTree &conf)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void	checkAndInvalidate (std::unique_ptr< ConfigTree > const &conf)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Methods for accessing subtrees
using	Children = std::vector<std::pair<std::string, Child>>
	Return type of getAllChildren(): an owning vector of (tag, view) pairs.
ConfigTree	getConfigSubtree (std::string const &root) const
std::optional< ConfigTree >	getConfigSubtreeOptional (std::string const &root) const
Range< SubtreeIterator >	getConfigSubtreeList (std::string const &root) const
Children	getAllChildren () const

Member Typedef Documentation

◆ Callback

using BaseLib::ConfigTree::Callback

Initial value:

 std::function<void(const std::string& filename,
                                        const std::string& path,
                                        const std::string& message)>

Type of the function objects used as callbacks.

Arguments of the callback:

filename the file being from which this ConfigTree has been read.
path the path in the tree where the message was generated.
message the message to be printed.

Definition at line 258 of file ConfigTree.h.

◆ Children

using BaseLib::ConfigTree::Children = std::vector<std::pair<std::string, Child>>

Return type of getAllChildren(): an owning vector of (tag, view) pairs.

Definition at line 503 of file ConfigTree.h.

◆ KeyType

using BaseLib::ConfigTree::KeyType = std::pair<Attr, std::string>

private

A pair (is attribute, tag/attribute name).

Definition at line 668 of file ConfigTree.h.

◆ PTree

using BaseLib::ConfigTree::PTree = boost::property_tree::ptree

The tree being wrapped by this class.

Definition at line 249 of file ConfigTree.h.

Member Enumeration Documentation

◆ Attr

enum class BaseLib::ConfigTree::Attr : bool

strongprivate

Used to indicate if dealing with XML tags or XML attributes.

Enumerator
TAG
ATTR

Definition at line 582 of file ConfigTree.h.

    {
        TAG = false,
        ATTR = true
    };

Constructor & Destructor Documentation

◆ ConfigTree() [1/4]

BaseLib::ConfigTree::ConfigTree	(	ConfigTree::PTree &&	top_level_tree,
		std::string	filename,
		Callback	error_cb,
		Callback	warning_cb )

explicit

Creates a new instance wrapping the given Boost Property Tree.

Parameters

top_level_tree	the top level Boost Property Tree
filename	the file from which the `tree` has been read
error_cb	callback function to be called on error.
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!

Definition at line 29 of file ConfigTree.cpp.

    : top_level_tree_(std::make_shared<PTree>(std::move(top_level_tree))),
      tree_(top_level_tree_.get()),
      onerror_(std::move(error_cb)),
      onwarning_(std::move(warning_cb))
{
    if (!onerror_)
    {
        OGS_FATAL("ConfigTree: No valid error handler provided.");
    }
    if (!onwarning_)
    {
        OGS_FATAL("ConfigTree: No valid warning handler provided.");
    }
 
    std::filesystem::path const filepath{filename};
    std::error_code ec;
    auto absolute_filepath = absolute(filepath, ec);
    if (ec)
    {
        DBUG(
            "ConfigTree: could not get the absolute path of '{}'. Using the "
            "path unmodified. Error code = {}",
            filepath.string(), ec.value());
        absolute_filepath = filepath;
    }
 
    // store absolute path s.t. we are safe if somebody changes the working
    // directory
    filepath_ = absolute_filepath;
    DBUG("ConfigTree: file path is {}.", filepath_.string());
 
    if (!exists(projectDirectory()))
    {
        DBUG("ConfigTree: The project directory '{}' does not exist.",
             projectDirectory().string());
    }
}

References DBUG(), filepath_, OGS_FATAL, onerror_, onwarning_, projectDirectory(), top_level_tree_, and tree_.

Referenced by ConfigTree(), ConfigTree(), ConfigTree(), BaseLib::ConfigTree::SubtreeIterator::SubtreeIterator(), BaseLib::ConfigTree::ValueIterator< ValueType >::ValueIterator(), checkAndInvalidate, checkAndInvalidate, getAllChildren(), getConfigParameter(), getConfigSubtree(), getConfigSubtreeOptional(), BaseLib::ConfigTree::ParameterIterator::operator*(), BaseLib::ConfigTree::SubtreeIterator::operator*(), BaseLib::ConfigTree::ValueIterator< ValueType >::operator*(), operator=(), and operator=().

◆ ConfigTree() [2/4]

BaseLib::ConfigTree::ConfigTree ( ConfigTree const & )

delete

copying is not compatible with the semantics of this class

References ConfigTree().

◆ ConfigTree() [3/4]

BaseLib::ConfigTree::ConfigTree ( ConfigTree && other )

After being moved from, other is in an undefined state and must not be used anymore!

Definition at line 83 of file ConfigTree.cpp.

    : top_level_tree_(std::move(other.top_level_tree_)),
      tree_(other.tree_),
      path_(std::move(other.path_)),
      filepath_(std::move(other.filepath_)),
      visited_params_(std::move(other.visited_params_)),
      have_read_data_(other.have_read_data_),
      onerror_(std::move(other.onerror_)),
      onwarning_(std::move(other.onwarning_))
{
    other.tree_ = nullptr;
}

References ConfigTree(), filepath_, have_read_data_, onerror_, onwarning_, path_, top_level_tree_, tree_, and visited_params_.

◆ ~ConfigTree()

BaseLib::ConfigTree::~ConfigTree ( )

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.

Definition at line 96 of file ConfigTree.cpp.

{
    if (std::uncaught_exceptions() > 0)
    {
        /* If the stack unwinds the check below shall be suppressed in order to
         * not accumulate false-positive configuration errors.
         */
        return;
    }
 
    try
    {
        checkAndInvalidate();
    }
    catch (std::exception& e)
    {
        ERR("{:s}", e.what());
        configtree_destructor_error_messages.emplace_front(e.what());
    }
}

References checkAndInvalidate(), configtree_destructor_error_messages, and ERR().

◆ ConfigTree() [4/4]

BaseLib::ConfigTree::ConfigTree	(	PTree const &	tree,
		ConfigTree const &	parent,
		std::string const &	root )

explicitprivate

Used for wrapping a subtree.

Definition at line 71 of file ConfigTree.cpp.

    : top_level_tree_(parent.top_level_tree_),
      tree_(&tree),
      path_(joinPaths(parent.path_, root)),
      filepath_(parent.filepath_),
      onerror_(parent.onerror_),
      onwarning_(parent.onwarning_)
{
    checkKeyname(root);
}

References ConfigTree(), checkKeyname(), filepath_, joinPaths(), onerror_, onwarning_, path_, top_level_tree_, and tree_.

Member Function Documentation

◆ assertNoSwallowedErrors()

void BaseLib::ConfigTree::assertNoSwallowedErrors ( )

static

Asserts that there have not been any errors reported in the destructor.

Definition at line 301 of file ConfigTree.cpp.

{
    if (configtree_destructor_error_messages.empty())
    {
        return;
    }
 
    ERR("ConfigTree: There have been errors when parsing the configuration "
        "file(s):");
 
    for (auto const& msg : configtree_destructor_error_messages)
    {
        ERR("{:s}", msg);
    }
 
    // Clear the error messages to avoid duplicate printing
    configtree_destructor_error_messages.clear();
 
    OGS_FATAL("There have been errors when parsing the configuration file(s).");
}

References configtree_destructor_error_messages, ERR(), and OGS_FATAL.

Referenced by OGSSimulation::finalize(), Simulation::initializeDataStructures(), and main().

◆ checkAndInvalidate()

void BaseLib::ConfigTree::checkAndInvalidate ( )

private

Checks if the top level of this tree has been read entirely (and not too often).

Postcondition: This method also invalidates the instance, i.e., afterwards it must not be used anymore!

Definition at line 455 of file ConfigTree.cpp.

{
    if (!tree_)
    {
        return;
    }
 
    // Note: due to a limitation in boost::property_tree it is not possible
    // to discriminate between <tag></tag> and <tag/> in the input file.
    // In both cases data() will be empty.
    if ((!have_read_data_) && !tree_->data().empty())
    {
        warning("The immediate data `" + shortString(tree_->data()) +
                "' of this tag has not been read.");
    }
 
    // iterate over children
    for (auto const& p : *tree_)
    {
        if (p.first != "<xmlattr>")
        {  // attributes are handled below
            markVisitedDecrement(Attr::TAG, p.first);
        }
    }
 
    // iterate over attributes
    if (auto attrs = tree_->get_child_optional("<xmlattr>"))
    {
        for (auto const& p : *attrs)
        {
            markVisitedDecrement(Attr::ATTR, p.first);
        }
    }
 
    for (auto const& p : visited_params_)
    {
        auto const& tag = p.first.second;
        auto const& count = p.second.count;
 
        switch (p.first.first)
        {
            case Attr::ATTR:
                if (count > 0)
                {
                    warning("XML attribute '" + tag + "' has been read " +
                            std::to_string(count) +
                            " time(s) more than it was present in the "
                            "configuration tree.");
                }
                else if (count < 0)
                {
                    warning("XML attribute '" + tag + "' has been read " +
                            std::to_string(-count) +
                            " time(s) less than it was present in the "
                            "configuration tree.");
                }
                break;
            case Attr::TAG:
                if (count > 0)
                {
                    warning("Key <" + tag + "> has been read " +
                            std::to_string(count) +
                            " time(s) more than it was present in the "
                            "configuration tree.");
                }
                else if (count < 0)
                {
                    warning("Key <" + tag + "> has been read " +
                            std::to_string(-count) +
                            " time(s) less than it was present in the "
                            "configuration tree.");
                }
        }
    }
 
    // The following invalidates this instance, s.t. it can not be read from it
    // anymore, but it also prevents double-checking.
    tree_ = nullptr;
}

References ATTR, have_read_data_, markVisitedDecrement(), shortString(), TAG, tree_, visited_params_, and warning().

Referenced by ~ConfigTree(), checkAndInvalidate, checkAndInvalidate, and operator=().

◆ checkConfigParameter()

void BaseLib::ConfigTree::checkConfigParameter	(	std::string const &	param,
		std::string_view const	value ) const

Assert that param has the given value.

Convenience method combining getConfigParameter(std::string const&) with a check.

Definition at line 167 of file ConfigTree.cpp.

{
    auto const parameter_value = getConfigParameter<std::string>(param);
    if (parameter_value != value)
    {
        error("For the tag <" + param + "> expected to read value '" +
              value.data() + "', but got '" + parameter_value + "'.");
    }
}

References error(), and getConfigParameter().

◆ checkKeyname()

void BaseLib::ConfigTree::checkKeyname ( std::string const & key ) const

private

Checks if key complies with the rules [a-z0-9_].

Definition at line 334 of file ConfigTree.cpp.

{
    if (key.empty())
    {
        error("Search for empty key.");
    }
    else if (key_chars_start.find(key.front()) == std::string::npos)
    {
        error("Key <" + key + "> starts with an illegal character.");
    }
    else if (key.find_first_not_of(key_chars, 1) != std::string::npos)
    {
        error("Key <" + key + "> contains illegal characters.");
    }
    else if (key.find("__") != std::string::npos)
    {
        // This is illegal because we use parameter names to generate doxygen
        // page names. Thereby "__" acts as a separator character. Choosing
        // other separators is not possible because of observed limitations
        // for valid doxygen page names.
        error("Key <" + key + "> contains double underscore.");
    }
}

References error(), key_chars, and key_chars_start.

Referenced by ConfigTree(), checkUnique(), checkUniqueAttr(), and peekConfigParameter().

◆ checkUnique()

void BaseLib::ConfigTree::checkUnique ( std::string const & key ) const

private

Asserts that the key has not been read yet.

Definition at line 374 of file ConfigTree.cpp.

{
    checkKeyname(key);
 
    if (visited_params_.find({Attr::TAG, key}) != visited_params_.end())
    {
        error("Key <" + key + "> has already been processed.");
    }
}

References checkKeyname(), error(), and visited_params_.

Referenced by getConfigParameterList(), getConfigParameterOptional(), getConfigSubtreeList(), getConfigSubtreeOptional(), ignoreConfigParameter(), and ignoreConfigParameterAll().

◆ checkUniqueAttr()

void BaseLib::ConfigTree::checkUniqueAttr ( std::string const & attr ) const

private

Asserts that the attribute attr has not been read yet.

Definition at line 384 of file ConfigTree.cpp.

{
    // Workaround for handling attributes with xml namespaces and uppercase
    // letters.
    if (attr.find(':') != std::string::npos)
    {
        auto pos = decltype(std::string::npos){0};
 
        // Replace colon and uppercase letters with an allowed character 'a'.
        // That means, attributes containing a colon are also allowed to contain
        // uppercase letters.
        auto attr2 = attr;
        do
        {
            pos = attr2.find_first_of(":ABCDEFGHIJKLMNOPQRSTUVWXYZ", pos);
            if (pos != std::string::npos)
            {
                attr2[pos] = 'a';
            }
        } while (pos != std::string::npos);
 
        checkKeyname(attr2);
    }
    else
    {
        checkKeyname(attr);
    }
 
    if (visited_params_.find({Attr::ATTR, attr}) != visited_params_.end())
    {
        error("Attribute '" + attr + "' has already been processed.");
    }
}

References checkKeyname(), error(), and visited_params_.

Referenced by getConfigAttributeOptional(), and ignoreConfigAttribute().

◆ error()

void BaseLib::ConfigTree::error ( std::string const & message ) const

private

Called if an error occurs. Will call the error callback.

This method only acts as a helper method and throws std::runtime_error.

Definition at line 274 of file ConfigTree.cpp.

{
    onerror_(filepath_.string(), path_, message);
    OGS_FATAL(
        "ConfigTree: The error handler does not break out of the normal "
        "control flow.");
}

References filepath_, OGS_FATAL, onerror_, and path_.

Referenced by checkConfigParameter(), checkKeyname(), checkUnique(), checkUniqueAttr(), getConfigAttribute(), getConfigAttributeOptional(), getConfigParameter(), getConfigParameterOptional(), getConfigParameterOptionalImpl(), getConfigSubtree(), getValue(), joinPaths(), markVisited(), and peekConfigParameter().

◆ getAllChildren()

ConfigTree::Children BaseLib::ConfigTree::getAllChildren ( ) const

Get all children of this ConfigTree.

Returns a vector of (tag, subtree) pairs for all children (subtrees and parameters) in the order they appear in the configuration tree. The return value is suitable for range-based for-loops and random access.

Definition at line 213 of file ConfigTree.cpp.

{
    Children children;
 
    // Hand out every child as its own subtree, mirroring getConfigSubtree():
    // mark each child tag as consumed in this (parent) tree so the parent does
    // not warn about the tags, then return a ConfigTree per child.  Each child
    // validates its own content on destruction, so any child whose sub-children
    // / attributes / immediate data are left unread warns exactly like an
    // unread getConfigSubtree() result.  <xmlattr> is skipped: attribute
    // storage is not a child element.  Duplicate tags are handled by
    // markVisited(), which increments the consumed count once per occurrence.
    for (auto const& [tag, subtree] : *tree_)
    {
        if (tag == "<xmlattr>")
        {
            continue;
        }
        markVisited(tag, Attr::TAG, false);
        children.emplace_back(tag, Child{ConfigTree(subtree, *this, tag)});
    }
 
    return children;
}

References ConfigTree(), markVisited(), TAG, and tree_.

◆ getConfigAttribute() [1/2]

template<typename T>

T BaseLib::ConfigTree::getConfigAttribute ( std::string const & attr ) const

Get XML attribute attr of type T for the current parameter.

Returns: the requested attribute's value.

Precondition: attr must not have been read before from the current parameter.

Definition at line 235 of file ConfigTree-impl.h.

{
    if (auto a = getConfigAttributeOptional<T>(attr))
    {
        return *a;
    }
 
    error("Did not find XML attribute with name '" + attr + "'.");
}

References error(), and getConfigAttributeOptional().

Referenced by ParameterLib::confirmThirdBaseExplicit(), ChemistryLib::PhreeqcIOData::createAqueousSolution(), and ParameterLib::createCoordinateSystemWithImplicitBase().

◆ getConfigAttribute() [2/2]

template<typename T>

T BaseLib::ConfigTree::getConfigAttribute	(	std::string const &	attr,
		T const &	default_value ) const

Get XML attribute attr of type T for the current parameter or the default_value.

This method has a similar behaviour as getConfigAttribute(std::string const&) except the default_value is returned if the attribute has not been found.

Returns: the requested attribute's value.

Precondition: attr must not have been read before from the current parameter.

Definition at line 246 of file ConfigTree-impl.h.

{
    if (auto a = getConfigAttributeOptional<T>(attr))
    {
        return *a;
    }
 
    return default_value;
}

References getConfigAttributeOptional().

◆ getConfigAttributeOptional()

template<typename T>

std::optional< T > BaseLib::ConfigTree::getConfigAttributeOptional ( std::string const & attr ) const

Get XML attribute attr of type T for the current parameter if present.

Returns: the requested attribute's value.

Precondition: attr must not have been read before from the current parameter.

Definition at line 258 of file ConfigTree-impl.h.

{
    checkUniqueAttr(attr);
    auto& ct = markVisited<T>(attr, Attr::ATTR, true);
 
    if (auto attrs = tree_->get_child_optional("<xmlattr>"))
    {
        if (auto a = attrs->get_child_optional(attr))
        {
            ++ct.count;  // count only if attribute has been found
            if (auto v = a->get_value_optional<T>())
            {
                return std::make_optional(*v);
            }
            error("Value for XML attribute '" + attr + "' `" +
                  shortString(a->data()) +
                  "' not convertible to the desired type.");
        }
    }
 
    return std::nullopt;
}

References ATTR, checkUniqueAttr(), error(), markVisited(), shortString(), and tree_.

Referenced by getConfigAttribute(), getConfigAttribute(), parseOutputMeshConfig(), and anonymous_namespace{ProjectData.cpp}::readSingleMesh().

◆ getConfigParameter() [1/3]

template<typename T>

T BaseLib::ConfigTree::getConfigParameter ( std::string const & param ) const

Get parameter param of type T from the configuration tree.

Returns: the value looked for.

Precondition: param must not have been read before from this ConfigTree.

Definition at line 113 of file ConfigTree-impl.h.

{
    if (auto p = getConfigParameterOptional<T>(param))
    {
        return *p;
    }
 
    error("Key <" + param + "> has not been found");
}

References error(), and getConfigParameterOptional().

◆ getConfigParameter() [2/3]

ConfigTree BaseLib::ConfigTree::getConfigParameter ( std::string const & param ) const

Get parameter param from the configuration tree.

Returns: the subtree representing the requested parameter

Precondition: param must not have been read before from this ConfigTree.

Definition at line 134 of file ConfigTree.cpp.

{
    auto ct = getConfigSubtree(param);
    if (ct.hasChildren())
    {
        error("Requested parameter <" + param + "> actually is a subtree.");
    }
    return ct;
}

References ConfigTree(), error(), and getConfigSubtree().

◆ getConfigParameter() [3/3]

template<typename T>

T BaseLib::ConfigTree::getConfigParameter	(	std::string const &	param,
		T const &	default_value ) const

Get parameter param of type T from the configuration tree or the default_value.

This method has a similar behaviour as getConfigParameter(std::string const&) except the default_value is returned if the attribute has not been found.

Precondition: param must not have been read before from this ConfigTree.

Definition at line 124 of file ConfigTree-impl.h.

{
    if (auto p = getConfigParameterOptional<T>(param))
    {
        return *p;
    }
 
    return default_value;
}

References getConfigParameterOptional().

◆ getConfigParameterList() [1/2]

template<typename T>

Range< ConfigTree::ValueIterator< T > > BaseLib::ConfigTree::getConfigParameterList ( std::string const & param ) const

Fetches all parameters with name param from the current level of the tree.

The return value is suitable to be used with range-base for-loops.

Precondition: param must not have been read before from this ConfigTree.

Definition at line 182 of file ConfigTree-impl.h.

{
    checkUnique(param);
    markVisited<T>(param, Attr::TAG, true);
 
    auto p = tree_->equal_range(param);
    return Range<ValueIterator<T>>(ValueIterator<T>(p.first, param, *this),
                                   ValueIterator<T>(p.second, param, *this));
}

References checkUnique(), markVisited(), TAG, and tree_.

Referenced by ProcessLib::HeatTransportBHE::createHeatTransportBHEProcess(), ProcessLib::LIE::HydroMechanics::createHydroMechanicsProcess(), ProcessLib::LIE::SmallDeformation::createSmallDeformationProcess(), ProcessLib::findProcessVariables(), and GeoLib::IO::BoostXmlGmlInterface::readPoints().

◆ getConfigParameterList() [2/2]

Range< ConfigTree::ParameterIterator > BaseLib::ConfigTree::getConfigParameterList ( std::string const & param ) const

Fetches all parameters with name param from the current level of the tree.

The return value is suitable to be used with range-base for-loops.

Precondition: param must not have been read before from this ConfigTree.

Definition at line 155 of file ConfigTree.cpp.

{
    checkUnique(param);
    markVisited(param, Attr::TAG, true);
 
    auto p = tree_->equal_range(param);
 
    return Range<ParameterIterator>(ParameterIterator(p.first, param, *this),
                                    ParameterIterator(p.second, param, *this));
}

References checkUnique(), markVisited(), TAG, and tree_.

◆ getConfigParameterOptional() [1/2]

template<typename T>

std::optional< T > BaseLib::ConfigTree::getConfigParameterOptional ( std::string const & param ) const

Get parameter param of type 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.

Precondition: param must not have been read before from this ConfigTree.

Definition at line 136 of file ConfigTree-impl.h.

{
    checkUnique(param);
 
    return getConfigParameterOptionalImpl(param, static_cast<T*>(nullptr));
}

References checkUnique(), and getConfigParameterOptionalImpl().

Referenced by ProjectData::ProjectData(), ProcessLib::createCentralDifferencesJacobianAssembler(), ChemistryLib::createChargeBalance(), ProcessLib::ComponentTransport::createComponentTransportProcess(), MaterialPropertyLib::createConstant(), ParameterLib::createConstantParameter(), NumLib::createConvergenceCriterionDeltaX(), NumLib::createConvergenceCriterionPerComponentDeltaX(), NumLib::createConvergenceCriterionPerComponentResidual(), NumLib::createConvergenceCriterionResidual(), ProcessLib::createDeactivatedSubdomain(), ProcessLib::ThermoRichardsFlow::createElasticityModel(), MaterialPropertyLib::createEmbeddedFracturePermeability(), ProcessLib::createForwardDifferencesJacobianAssembler(), ProcessLib::HMPhaseField::createHMPhaseFieldProcess(), ProcessLib::HT::createHTProcess(), ProcessLib::LIE::HydroMechanics::createHydroMechanicsProcess(), NumLib::createNewtonRaphsonSolverParameters(), NumLib::createNonlinearSolver(), ProcessLib::PhaseField::createPhaseFieldProcess(), ProcessLib::RichardsComponentTransport::createRichardsComponentTransportProcess(), ProcessLib::RichardsMechanics::createRichardsMechanicsProcess(), MaterialPropertyLib::createSaturationVanGenuchten(), ProcessLib::SmallDeformation::createSmallDeformationProcess(), ProcessLib::TH2M::createTH2MProcess(), ProcessLib::ThermoHydroMechanics::createThermoHydroMechanicsProcess(), ProcessLib::ThermoMechanics::createThermoMechanicsProcess(), ProcessLib::ThermoRichardsFlow::createThermoRichardsFlowProcess(), ProcessLib::ThermoRichardsMechanics::createThermoRichardsMechanicsProcessStage2(), anonymous_namespace{ProcessVariable.cpp}::findMeshInConfig(), ParameterLib::findOptionalTagParameter(), getConfigParameter(), getConfigParameter(), NumLib::parseFixedTimeStepping(), MathLib::LinearSolverOptionsParser< EigenLisLinearSolver >::parseNameAndOptions(), ProcessLib::parseNeumannBoundaryCondition(), ProcessLib::parseRobinBoundaryCondition(), and anonymous_namespace{ProjectData.cpp}::readMeshes().

◆ getConfigParameterOptional() [2/2]

std::optional< ConfigTree > BaseLib::ConfigTree::getConfigParameterOptional ( std::string const & param ) const

Get parameter param from the configuration tree if present.

Returns: the subtree representing the requested parameter

Precondition: param must not have been read before from this ConfigTree.

Definition at line 144 of file ConfigTree.cpp.

{
    auto ct = getConfigSubtreeOptional(param);
    if (ct && ct->hasChildren())
    {
        error("Requested parameter <" + param + "> actually is a subtree.");
    }
    return ct;
}

References error(), and getConfigSubtreeOptional().

◆ getConfigParameterOptionalImpl() [1/2]

template<typename T>

std::optional< std::vector< T > > BaseLib::ConfigTree::getConfigParameterOptionalImpl	(	std::string const &	param,
		std::vector< T > *	) const

private

Implementation of reading a vector of values of type T.

Definition at line 157 of file ConfigTree-impl.h.

{
    if (auto p = getConfigSubtreeOptional(param))
    {
        std::string const raw = p->getValue<std::string>();
 
        std::size_t bad_idx = 0;
        if (auto parsed = BaseLib::tryParseVector<T>(raw, &bad_idx))
        {
            return parsed;  // OK
        }
 
        // preserve original error wording & token index
        error("Value for key <" + param + "> `" + shortString(raw) +
              "' not convertible to a vector of the desired type."
              " Could not convert token no. " +
              std::to_string(bad_idx) + ".");
        return std::nullopt;  // not reached
    }
 
    return std::nullopt;
}

References error(), getConfigSubtreeOptional(), shortString(), and BaseLib::tryParseVector().

◆ getConfigParameterOptionalImpl() [2/2]

template<typename T>

std::optional< T > BaseLib::ConfigTree::getConfigParameterOptionalImpl	(	std::string const &	param,
		T *	) const

private

Default implementation of reading a value of type T.

Definition at line 145 of file ConfigTree-impl.h.

{
    if (auto p = getConfigSubtreeOptional(param))
    {
        return p->getValue<T>();
    }
 
    return std::nullopt;
}

References getConfigSubtreeOptional().

Referenced by getConfigParameterOptional().

◆ getConfigSubtree()

ConfigTree BaseLib::ConfigTree::getConfigSubtree ( std::string const & root ) const

Get the subtree rooted at root

If root is not found error() is called.

Precondition: root must not have been read before from this ConfigTree.

Definition at line 178 of file ConfigTree.cpp.

{
    if (auto t = getConfigSubtreeOptional(root))
    {
        return std::move(*t);
    }
    error("Key <" + root + "> has not been found.");
}

References ConfigTree(), error(), and getConfigSubtreeOptional().

◆ getConfigSubtreeList()

Range< ConfigTree::SubtreeIterator > BaseLib::ConfigTree::getConfigSubtreeList ( std::string const & root ) const

Get all subtrees that have a root root from the current level of the tree.

The return value is suitable to be used with range-base for-loops.

Precondition: root must not have been read before from this ConfigTree.

Definition at line 201 of file ConfigTree.cpp.

{
    checkUnique(root);
    markVisited(root, Attr::TAG, true);
 
    auto p = tree_->equal_range(root);
 
    return Range<SubtreeIterator>(SubtreeIterator(p.first, root, *this),
                                  SubtreeIterator(p.second, root, *this));
}

References checkUnique(), markVisited(), TAG, and tree_.

Referenced by ApplicationsLib::TestDefinition::TestDefinition(), ChemistryLib::SelfContainedSolverData::createChemicalReactionData(), MaterialLib::Solids::createConstitutiveRelationsGeneric(), MaterialPropertyLib::createFunction(), ParameterLib::createFunctionParameter(), ParameterLib::createGroupBasedParameter(), ProcessLib::LIE::HydroMechanics::createHydroMechanicsProcess(), MaterialPropertyLib::createLinear(), ProcessLib::createOutputs(), ProcessLib::createPerProcessData(), ProcessLib::LIE::SmallDeformation::createSmallDeformationProcess(), InSituLib::Initialize(), NumLib::parseFixedTimeStepping(), ProjectData::parseLinearSolvers(), NumLib::parseLocalCoupling(), ProjectData::parseNonlinearSolvers(), ProjectData::parseParameters(), ProjectData::parseProcesses(), ProjectData::parseProcessVariables(), GeoLib::IO::BoostXmlGmlInterface::readPolylines(), and GeoLib::IO::BoostXmlGmlInterface::readSurfaces().

◆ getConfigSubtreeOptional()

std::optional< ConfigTree > BaseLib::ConfigTree::getConfigSubtreeOptional ( std::string const & root ) const

Get the subtree rooted at root if present

Precondition: root must not have been read before from this ConfigTree.

Definition at line 187 of file ConfigTree.cpp.

{
    checkUnique(root);
 
    if (auto subtree = tree_->get_child_optional(root))
    {
        markVisited(root, Attr::TAG, false);
        return ConfigTree(*subtree, *this, root);
    }
    markVisited(root, Attr::TAG, true);
    return std::nullopt;
}

References ConfigTree(), checkUnique(), markVisited(), TAG, and tree_.

Referenced by ProcessLib::ProcessVariable::ProcessVariable(), ParameterLib::checkThirdBaseExistanceFor2D(), ChemistryLib::PhreeqcIOData::createChemicalSystem(), anonymous_namespace{CreateComponent.cpp}::createComponent(), ProcessLib::ComponentTransport::createComponentTransportProcess(), MaterialLib::Solids::createConstitutiveRelationIce(), ParameterLib::createCoordinateSystemWithImplicitBase(), ProcessLib::createDeactivatedSubdomain(), ProcessLib::createDeactivatedSubdomains(), MaterialLib::Solids::Ehlers::createEhlers(), ProcessLib::HeatTransportBHE::BHE::createFlowAndTemperatureControl(), ProcessLib::HT::createHTProcess(), ProcessLib::HydroMechanics::createHydroMechanicsProcess(), ProcessLib::LIE::HydroMechanics::createHydroMechanicsProcess(), ProcessLib::createInitialStress(), ProcessLib::LiquidFlow::createLiquidFlowProcess(), MaterialPropertyLib::createMedium(), MaterialLib::Solids::MFront::createMFrontConfig(), NumLib::createNonlinearSolver(), NumLib::createNumericalStabilization(), ProcessLib::createOutputConfig(), anonymous_namespace{CreatePhase.cpp}::createPhase(), ProcessLib::RichardsMechanics::createRichardsMechanicsProcess(), MeshGeoToolsLib::createSearchLengthAlgorithm(), ProcessLib::createSecondaryVariables(), ProcessLib::SteadyStateDiffusion::createSteadyStateDiffusion(), ProcessLib::createTimeLoop(), anonymous_namespace{ProcessVariable.cpp}::findMeshInConfig(), getConfigParameterOptional(), getConfigParameterOptionalImpl(), getConfigParameterOptionalImpl(), getConfigSubtree(), NumLib::parseCoupling(), MathLib::LinearSolverOptionsParser< EigenLinearSolver >::parseNameAndOptions(), MathLib::LinearSolverOptionsParser< PETScLinearSolver >::parseNameAndOptions(), parseOverwriteMeshData(), anonymous_namespace{ProjectData.cpp}::readMeshes(), anonymous_namespace{ProjectData.cpp}::readRasters(), and anonymous_namespace{CreateMFrontGeneric.cpp}::readStateVariablesInitialValueProperties().

◆ getValue()

template<typename T>

T BaseLib::ConfigTree::getValue ( ) const

Get the plain data contained in the current level of the tree.

Returns: the data converted to the type T

Precondition: The data must not have been read before.

Definition at line 217 of file ConfigTree-impl.h.

{
    if (have_read_data_)
    {
        error("The data of this subtree has already been read.");
    }
 
    have_read_data_ = true;
 
    if (auto v = tree_->get_value_optional<T>())
    {
        return *v;
    }
    error("Value `" + shortString(tree_->data()) +
          "' is not convertible to the desired type.");
}

References error(), have_read_data_, shortString(), and tree_.

Referenced by ParameterLib::parseBase1OrBase2(), MaterialPropertyLib::anonymous_namespace{CreateFunction.cpp}::parseExpressionList(), parseOutputMeshConfig(), and anonymous_namespace{ProjectData.cpp}::readSingleMesh().

◆ hasChildren()

bool BaseLib::ConfigTree::hasChildren ( ) const

private

Checks if this tree has any children.

Definition at line 440 of file ConfigTree.cpp.

{
    auto const& tree = *tree_;
    if (tree.begin() == tree.end())
    {
        return false;  // no children
    }
    if (tree.front().first == "<xmlattr>" && (++tree.begin()) == tree.end())
    {
        return false;  // only attributes
    }
 
    return true;
}

References tree_.

◆ ignoreConfigAttribute()

void BaseLib::ConfigTree::ignoreConfigAttribute ( std::string const & attr ) const

Tell this instance to ignore the XML attribute attr.

This method is used to avoid warning messages.

Precondition: attr must not have been read before from this ConfigTree.

Definition at line 246 of file ConfigTree.cpp.

{
    checkUniqueAttr(attr);
 
    // Exercise: Guess what not! (hint: if not found, peek only)
    // Btw. (not a hint) tree_->find() does not seem to work here.
    bool peek_only = !tree_->get_child_optional("<xmlattr>." + attr);
 
    markVisited(attr, Attr::ATTR, peek_only);
}

References ATTR, checkUniqueAttr(), markVisited(), and tree_.

◆ ignoreConfigParameter()

void BaseLib::ConfigTree::ignoreConfigParameter ( std::string const & param ) const

Tell this instance to ignore parameter param.

This method is used to avoid warning messages.

Precondition: param must not have been read before from this ConfigTree.

Definition at line 238 of file ConfigTree.cpp.

{
    checkUnique(param);
    // if not found, peek only
    bool peek_only = tree_->find(param) == tree_->not_found();
    markVisited(param, Attr::TAG, peek_only);
}

References checkUnique(), markVisited(), TAG, and tree_.

Referenced by NumLib::createTimeStepper(), and MathLib::ignoreOtherLinearSolvers().

◆ ignoreConfigParameterAll()

void BaseLib::ConfigTree::ignoreConfigParameterAll ( std::string const & param ) const

Tell this instance to ignore all parameters param on the current level of the tree.

This method is used to avoid warning messages.

Precondition: param must not have been read before from this ConfigTree.

Definition at line 257 of file ConfigTree.cpp.

{
    checkUnique(param);
    auto& ct = markVisited(param, Attr::TAG, true);
 
    auto p = tree_->equal_range(param);
    for (auto it = p.first; it != p.second; ++it)
    {
        ++ct.count;
    }
}

References checkUnique(), markVisited(), TAG, and tree_.

◆ joinPaths()

std::string BaseLib::ConfigTree::joinPaths	(	std::string const &	p1,
		std::string const &	p2 ) const

private

Used to generate the path of a subtree.

Definition at line 358 of file ConfigTree.cpp.

{
    if (p2.empty())
    {
        error("Second path to be joined is empty.");
    }
 
    if (p1.empty())
    {
        return p2;
    }
 
    return p1 + pathseparator + p2;
}

References error(), and pathseparator.

Referenced by ConfigTree().

◆ markVisited() [1/2]

ConfigTree::CountType & BaseLib::ConfigTree::markVisited	(	std::string const &	key,
		Attr const	is_attr,
		bool const	peek_only ) const

private

Keeps track of the key key and its value type ConfigTree.

This method asserts that a key is read always with the same type.

param peek_only if true, do not change the read-count of the given key.

Definition at line 418 of file ConfigTree.cpp.

{
    return markVisited<ConfigTree>(key, is_attr, peek_only);
}

References markVisited().

◆ markVisited() [2/2]

template<typename T>

ConfigTree::CountType & BaseLib::ConfigTree::markVisited	(	std::string const &	key,
		Attr const	is_attr,
		bool	peek_only ) const

private

Keeps track of the key key and its value type T.

This method asserts that a key is read always with the same type.

param peek_only if true, do not change the read-count of the given key.

Definition at line 283 of file ConfigTree-impl.h.

{
    auto const type = std::type_index(typeid(T));
 
    auto p = visited_params_.emplace(std::make_pair(is_attr, key),
                                     CountType{peek_only ? 0 : 1, type});
 
    if (!p.second)
    {  // no insertion happened
        auto& v = p.first->second;
        if (v.type == type)
        {
            if (!peek_only)
            {
                ++v.count;
            }
        }
        else
        {
            error("There already was an attempt to obtain key <" + key +
                  "> with type '" + BaseLib::demangle(v.type.name()) +
                  "' (now: '" + type.name() + "').");
        }
    }
 
    return p.first->second;
}

References BaseLib::demangle(), error(), and visited_params_.

Referenced by getAllChildren(), getConfigAttributeOptional(), getConfigParameterList(), getConfigSubtreeList(), getConfigSubtreeOptional(), ignoreConfigAttribute(), ignoreConfigParameter(), ignoreConfigParameterAll(), and markVisited().

◆ markVisitedDecrement()

void BaseLib::ConfigTree::markVisitedDecrement	(	Attr const	is_attr,
		std::string const &	key ) const

private

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

Definition at line 425 of file ConfigTree.cpp.

{
    auto const type = std::type_index(typeid(nullptr));
 
    auto p = visited_params_.emplace(std::make_pair(is_attr, key),
                                     CountType{-1, type});
 
    if (!p.second)
    {  // no insertion happened
        auto& v = p.first->second;
        --v.count;
    }
}

References visited_params_.

Referenced by checkAndInvalidate().

◆ onerror()

void BaseLib::ConfigTree::onerror	(	std::string const &	filename,
		std::string const &	path,
		std::string const &	message )

static

Default error callback function Will throw std::runtime_error

Definition at line 287 of file ConfigTree.cpp.

{
    OGS_FATAL("ConfigTree: In file `{:s}' at path <{:s}>: {:s}", filename, path,
              message);
}

References OGS_FATAL.

Referenced by BaseLib::makeConfigTree().

◆ onwarning()

void BaseLib::ConfigTree::onwarning	(	std::string const &	filename,
		std::string const &	path,
		std::string const &	message )

static

Default warning callback function Will print a warning message

Definition at line 294 of file ConfigTree.cpp.

{
    WARN("ConfigTree: In file `{:s}' at path <{:s}>: {:s}", filename, path,
         message);
}

References WARN().

Referenced by BaseLib::makeConfigTree().

◆ operator=() [1/2]

ConfigTree & BaseLib::ConfigTree::operator= ( ConfigTree && other )

After being moved from, other is in an undefined state and must not be used anymore!

Definition at line 117 of file ConfigTree.cpp.

{
    checkAndInvalidate();
 
    top_level_tree_ = std::move(other.top_level_tree_);
    tree_ = other.tree_;
    other.tree_ = nullptr;
    path_ = std::move(other.path_);
    filepath_ = std::move(other.filepath_);
    visited_params_ = std::move(other.visited_params_);
    have_read_data_ = other.have_read_data_;
    onerror_ = std::move(other.onerror_);
    onwarning_ = std::move(other.onwarning_);
 
    return *this;
}

References ConfigTree(), checkAndInvalidate(), filepath_, have_read_data_, onerror_, onwarning_, path_, top_level_tree_, tree_, and visited_params_.

◆ operator=() [2/2]

ConfigTree & BaseLib::ConfigTree::operator= ( ConfigTree const & )

delete

copying is not compatible with the semantics of this class

References ConfigTree().

◆ peekConfigParameter()

template<typename T>

T BaseLib::ConfigTree::peekConfigParameter ( std::string const & param ) const

Peek at a parameter param of type 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&).

Definition at line 194 of file ConfigTree-impl.h.

{
    checkKeyname(param);
 
    if (auto p = tree_->get_child_optional(param))
    {
        try
        {
            return p->get_value<T>();
        }
        catch (boost::property_tree::ptree_bad_data const&)
        {
            error("Value for key <" + param + "> `" + shortString(p->data()) +
                  "' not convertible to the desired type.");
        }
    }
    else
    {
        error("Key <" + param + "> has not been found");
    }
}

References checkKeyname(), error(), shortString(), and tree_.

◆ projectDirectory()

std::filesystem::path BaseLib::ConfigTree::projectDirectory ( ) const

Definition at line 269 of file ConfigTree.cpp.

{
    return filepath_.parent_path();
}

References filepath_.

Referenced by ConfigTree(), ChemistryLib::createChemicalSolverInterface< ChemicalSolver::Phreeqc >(), ProcessLib::ComponentTransport::createComponentTransportProcess(), MaterialLib::Solids::MFront::createMFrontConfig(), ProcessLib::createOutputConfig(), MathLib::parsePiecewiseLinearCurveConfig(), anonymous_namespace{ProjectData.cpp}::readMeshes(), and GeoLib::IO::readRaster().

◆ projectFilePath()

std::filesystem::path const & BaseLib::ConfigTree::projectFilePath ( ) const

inline

Used to get the project file name.

Definition at line 297 of file ConfigTree.h.

297{ return filepath_; }

References filepath_.

◆ shortString()

std::string BaseLib::ConfigTree::shortString ( std::string const & s )

staticprivate

returns a short string at suitable for error/warning messages

Definition at line 322 of file ConfigTree.cpp.

{
    const std::size_t maxlen = 100;
 
    if (s.size() < maxlen)
    {
        return s;
    }
 
    return s.substr(0, maxlen - 3) + "...";
}

Referenced by checkAndInvalidate(), getConfigAttributeOptional(), getConfigParameterOptionalImpl(), getValue(), and peekConfigParameter().

◆ warning()

void BaseLib::ConfigTree::warning ( std::string const & message ) const

private

Called for printing warning messages. Will call the warning callback. This method only acts as a helper method.

Definition at line 282 of file ConfigTree.cpp.

{
    onwarning_(filepath_.string(), path_, message);
}

References filepath_, onwarning_, and path_.

Referenced by checkAndInvalidate().

◆ checkAndInvalidate [1/3]

void checkAndInvalidate ( ConfigTree & conf )

friend

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 535 of file ConfigTree.cpp.

{
    conf.checkAndInvalidate();
}

References ConfigTree(), and checkAndInvalidate().

◆ checkAndInvalidate [2/3]

void checkAndInvalidate ( ConfigTree *const conf )

friend

Check if conf has been read entirely and invalidate it.

This method can safely be called on nullptr's.

See also: ConfigTree::checkAndInvalidate()

Definition at line 540 of file ConfigTree.cpp.

{
    if (conf)
    {
        conf->checkAndInvalidate();
    }
}

References ConfigTree(), and checkAndInvalidate().

◆ checkAndInvalidate [3/3]

void checkAndInvalidate ( std::unique_ptr< ConfigTree > const & conf )

friend

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 548 of file ConfigTree.cpp.

{
    if (conf)
    {
        conf->checkAndInvalidate();
    }
}

Member Data Documentation

◆ filepath_

std::filesystem::path BaseLib::ConfigTree::filepath_

private

The path of the file from which this tree has been read.

Definition at line 665 of file ConfigTree.h.

Referenced by ConfigTree(), ConfigTree(), ConfigTree(), error(), operator=(), projectDirectory(), projectFilePath(), and warning().

◆ have_read_data_

bool BaseLib::ConfigTree::have_read_data_ = false

mutableprivate

Indicates if the plain data contained in this tree has already been read.

Definition at line 681 of file ConfigTree.h.

Referenced by ConfigTree(), checkAndInvalidate(), getValue(), and operator=().

◆ key_chars

const std::string BaseLib::ConfigTree::key_chars = key_chars_start + "_0123456789"

staticprivate

Set of allowed characters in a key name.

Definition at line 693 of file ConfigTree.h.

Referenced by checkKeyname().

◆ key_chars_start

const std::string BaseLib::ConfigTree::key_chars_start = "abcdefghijklmnopqrstuvwxyz"

staticprivate

Set of allowed characters as the first letter of a key name.

Definition at line 690 of file ConfigTree.h.

Referenced by checkKeyname().

◆ onerror_

Callback BaseLib::ConfigTree::onerror_

private

Custom error callback.

Definition at line 683 of file ConfigTree.h.

Referenced by ConfigTree(), ConfigTree(), ConfigTree(), error(), and operator=().

◆ onwarning_

Callback BaseLib::ConfigTree::onwarning_

private

Custom warning callback.

Definition at line 684 of file ConfigTree.h.

Referenced by ConfigTree(), ConfigTree(), ConfigTree(), operator=(), and warning().

◆ path_

std::string BaseLib::ConfigTree::path_

private

A path printed in error/warning messages.

Definition at line 662 of file ConfigTree.h.

Referenced by ConfigTree(), ConfigTree(), error(), operator=(), and warning().

◆ pathseparator

const char BaseLib::ConfigTree::pathseparator = '/'

staticprivate

Character separating two path components.

Definition at line 687 of file ConfigTree.h.

Referenced by joinPaths().

◆ top_level_tree_

std::shared_ptr<PTree const> BaseLib::ConfigTree::top_level_tree_

private

Root of the tree.

Owned by all ConfigTree instances that might access any part of it.

Definition at line 656 of file ConfigTree.h.

Referenced by ConfigTree(), ConfigTree(), ConfigTree(), and operator=().

◆ tree_

PTree const* BaseLib::ConfigTree::tree_

private

The wrapped tree.

Definition at line 659 of file ConfigTree.h.

Referenced by ConfigTree(), ConfigTree(), ConfigTree(), checkAndInvalidate(), getAllChildren(), getConfigAttributeOptional(), getConfigParameterList(), getConfigSubtreeList(), getConfigSubtreeOptional(), getValue(), hasChildren(), ignoreConfigAttribute(), ignoreConfigParameter(), ignoreConfigParameterAll(), operator=(), and peekConfigParameter().

◆ visited_params_

std::map<KeyType, CountType> BaseLib::ConfigTree::visited_params_

mutableprivate

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.

Definition at line 677 of file ConfigTree.h.

Referenced by ConfigTree(), checkAndInvalidate(), checkUnique(), checkUniqueAttr(), markVisited(), markVisitedDecrement(), and operator=().

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

Detailed Description

Classes

Public Types

Public Member Functions

Static Public Member Functions

Private Types

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Friends

Methods for accessing subtrees

Member Typedef Documentation

◆ Callback

◆ Children

◆ KeyType

◆ PTree

Member Enumeration Documentation

◆ Attr

Constructor & Destructor Documentation

◆ ConfigTree() [1/4]

◆ ConfigTree() [2/4]

◆ ConfigTree() [3/4]

◆ ~ConfigTree()

◆ ConfigTree() [4/4]

Member Function Documentation

◆ assertNoSwallowedErrors()

◆ checkAndInvalidate()

◆ checkConfigParameter()

◆ checkKeyname()

◆ checkUnique()

◆ checkUniqueAttr()

◆ error()

◆ getAllChildren()

◆ getConfigAttribute() [1/2]

◆ getConfigAttribute() [2/2]

◆ getConfigAttributeOptional()

◆ getConfigParameter() [1/3]

◆ getConfigParameter() [2/3]

◆ getConfigParameter() [3/3]

◆ getConfigParameterList() [1/2]

◆ getConfigParameterList() [2/2]

◆ getConfigParameterOptional() [1/2]

◆ getConfigParameterOptional() [2/2]

◆ getConfigParameterOptionalImpl() [1/2]

◆ getConfigParameterOptionalImpl() [2/2]

◆ getConfigSubtree()

◆ getConfigSubtreeList()

◆ getConfigSubtreeOptional()

◆ getValue()

◆ hasChildren()

◆ ignoreConfigAttribute()

◆ ignoreConfigParameter()

◆ ignoreConfigParameterAll()

◆ joinPaths()

◆ markVisited() [1/2]

◆ markVisited() [2/2]

◆ markVisitedDecrement()

◆ onerror()

◆ onwarning()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ peekConfigParameter()

◆ projectDirectory()

◆ projectFilePath()

◆ shortString()

◆ warning()

Friends And Related Symbol Documentation

◆ checkAndInvalidate [1/3]

◆ checkAndInvalidate [2/3]

◆ checkAndInvalidate [3/3]

Member Data Documentation

◆ filepath_

◆ have_read_data_

◆ key_chars

◆ key_chars_start

◆ onerror_

◆ onwarning_

◆ path_

◆ pathseparator