Config Utilities

Allows reading configuration entries from YAML files. More...

Collaboration diagram for Config Utilities:

Typedefs
using	Utopia::DataIO::Config = YAML::Node
	Type of a variadic dictionary-like data structure used throughout Utopia.

Functions
template<typename ReturnType >
ReturnType	Utopia::get_as (const std::string &key, const DataIO::Config &node)
	This function is a wrapper around the yaml-cpp YAML::Node::as function.
template<typename ReturnType >
ReturnType	Utopia::get_as (const std::string &key, const DataIO::Config &node, ReturnType fallback)
	Like Utopia::get_as, but instead of KeyError, returns a fallback value.
template<DimType dim>
SpaceVecType< dim >	Utopia::get_as_SpaceVec (const std::string &key, const DataIO::Config &node)
	Special case of Utopia::get_as to retrieve an entry as SpaceVec.
template<DimType dim>
MultiIndexType< dim >	Utopia::get_as_MultiIndex (const std::string &key, const DataIO::Config &node)
	Special case of Utopia::get_as to retrieve an entry as MultiIndex.

Detailed Description

Allows reading configuration entries from YAML files.

Configuration file Module

Overview

This module implements functions which allow for improved access to yaml-cpp processed yaml-files. The primary focus lies on improved exceptions and usability, mainly through the Utopia::get_as function.

Utopia relies heavily on the use of YAML configuration files. These files and substructures of it are available as so called "config nodes", Utopia::DataIO::Config objects, which are hierarchically nested maps, sequences, and scalars.

When retrieving values from these nodes, a type cast becomes necessary. While the library used for YAML reading provides such a function, we found it more convenient to define some thin wrappers around them, which supply more information when something goes wrong.

To remember the order of arguments, this sentence can be employed: get_as a double: the entry named my_double from this cfg node. Of course, YAML has no types associated with each entry; the Utopia::get_as function tries to do this conversion and, if it fails, throws an exception.

Implementation

The core of this module consists of the get_as function, which i conjunction with improve_yaml_exception works to improve error messages and simplifies the syntax of converting yaml nodes to c++ types. Additionally, specializations for non-standard types are provided, e.g. for working with types from the Armadillo linear algebra package.

Typedef Documentation

Config

using Utopia::DataIO::Config = typedef YAML::Node

Type of a variadic dictionary-like data structure used throughout Utopia.

Function Documentation

get_as() [1/2]

template<typename ReturnType >

ReturnType Utopia::get_as	(	const std::string &	key,
		const DataIO::Config &	node
	)

This function is a wrapper around the yaml-cpp YAML::Node::as function.

It enhances the error messages that can occur in a read operation.

Example:

using namespace Utopia;
 
auto cfg = YAML::Load("{my_double: 3.14, my_int: 42, my_str: foo}");
auto my_double = get_as<double>("my_double", cfg);
auto my_uint = get_as<unsigned int>("my_int", cfg);
auto my_int = get_as<int>("my_int", cfg);
auto my_str = get_as<std::string>("my_str", cfg);

Note

This method may throw Utopia::KeyError, which contains the name of the key that could not be accessed. Also, the conversion needs to be supported by the underlying YAML library.

Template Parameters

ReturnType

The type to evaluate from the YAML::Node

Parameters

key	The key that is to be read
node	The node to read the entry with the given key from

Returns

The value of node[key], cast to ReturnType

Exceptions

Utopia::KeyError	On missing key
YAML::Exception	On bad conversions or other YAML-related errors

{
    try
    {
        return node[key].template as< ReturnType >();
    }
    catch (YAML::Exception& e)
    {
        if (not node[key])
        {
            throw KeyError(key, node);
        }
        // else: throw an improved error message
        throw DataIO::improve_yaml_exception(e, node,
                                             "Could not read key '" + key +
                                             "' from given config node!");
    }
    catch (std::exception& e)
    {
        // Some other exception; provide at least some info and context
        std::cerr << boost::core::demangle(typeid(e).name())
                  << " occurred during reading key '" << key
                  << "' from config!" << std::endl;
 
        // Re-throw the original exception
        throw;
    }
    catch (...)
    {
        throw std::runtime_error("Unexpected exception occurred during "
                                 "reading key '" + key + "'' from config!");
    }
}

get_as() [2/2]

template<typename ReturnType >

ReturnType Utopia::get_as	(	const std::string &	key,
		const DataIO::Config &	node,
		ReturnType	fallback
	)

Like Utopia::get_as, but instead of KeyError, returns a fallback value.

{
    try
    {
        return get_as< ReturnType >(key, node);
    }
    catch (KeyError&)
    {
        return fallback;
    }
    // All other errors will (rightly) be thrown
}

get_as_MultiIndex()

template<DimType dim>

MultiIndexType< dim > Utopia::get_as_MultiIndex	(	const std::string &	key,
		const DataIO::Config &	node
	)

Special case of Utopia::get_as to retrieve an entry as MultiIndex.

Template Parameters

dim	The dimensionality of the returned Utopia::MultiIndexType

{
    return DataIO::get_as_arma_vec< MultiIndexType< dim >, dim >(key, node);
}

get_as_SpaceVec()

template<DimType dim>

SpaceVecType< dim > Utopia::get_as_SpaceVec	(	const std::string &	key,
		const DataIO::Config &	node
	)

Special case of Utopia::get_as to retrieve an entry as SpaceVec.

Template Parameters

dim	The dimensionality of the returned Utopia::SpaceVecType

{
    return DataIO::get_as_arma_vec< SpaceVecType< dim >, dim >(key, node);
}