smash::Configuration Class Reference

#include <configuration.h>

Interface to the SMASH configuration files.

The configuration is created from a YAML file and then stores a nested map of maps (normally a tree, but YAML allows it to be cyclic - even though we don't want that feature).

For the typical usage in SMASH one needs to read the value once. In that case, use the Configuration::take function:

double sigma = config.take({"General", "SIGMA"});

Note the curly braces in the function call. It is a std::initializer_list of strings. This allows an arbitrary nesting depth via the same function. But as a consequence the keys must all be given as constant strings at compile time.

If you need to access the configuration values from a run-time string you can use Configuration::operator[]. This returns a Configuration object that references the respective sub-tree.

By taking values (instead of just reading), the configuration object should be empty at the end of the initialization. If the object is not empty, SMASH will print a warning (using Configuration::unused_values_report). This can be important for the user to discover typos in his configuration file (or command line parameters).

Definition at line 464 of file configuration.h.

Collaboration diagram for smash::Configuration:

Classes
struct	FileDoesNotExist
struct	IncorrectTypeInAssignment
struct	ParseError
class	Value
	Return type of Configuration::take that automatically determines the target type. More...

Public Member Functions
	Configuration (const bf::path &path)
	Reads config.yaml from the specified path. More...
	Configuration (const bf::path &path, const bf::path &filename)
	Reads a YAML config file from the specified path. More...
	Configuration (const char *yaml)
	Configuration (const Configuration &)=default
	If you want to copy this you're doing it wrong. More...
Configuration &	operator= (const Configuration &)=default
	If you want to copy this you're doing it wrong. More...
	Configuration (Configuration &&)=default
	Moving is fine. More...
Configuration &	operator= (Configuration &&)=default
	Moving is fine. More...
void	merge_yaml (const std::string &yaml)
	Merge the configuration in yaml into the existing tree. More...
std::vector< std::string >	list_upmost_nodes ()
	Lists all YAML::Nodes from the configuration setup. More...
Value	take (std::initializer_list< const char * > keys)
	The default interface for SMASH to read configuration values. More...
template<typename T >
T	take (std::initializer_list< const char * > keys, T default_value)
Value	read (std::initializer_list< const char * > keys) const
	Additional interface for SMASH to read configuration values without removing them. More...
template<typename T >
T	read (std::initializer_list< const char * > keys, T default_value)
void	remove_all_but (const std::string &key)
	Removes all entries in the map except for key. More...
template<typename T >
Configuration	operator[] (T &&key)
	Access to the YAML::Node behind the requested keys. More...
template<typename T >
Configuration &	operator= (T &&value)
	Assignment overwrites the value of the current YAML node. More...
bool	has_value_including_empty (std::initializer_list< const char * > keys) const
	Returns if there is a (maybe empty) value behind the requested keys. More...
bool	has_value (std::initializer_list< const char * > keys) const
	Returns whether there is a non-empty value behind the requested keys. More...
std::string	unused_values_report () const
	Returns a string listing the key/value pairs that have not been taken yet. More...
std::string	to_string () const
	Returns a YAML string of the current tree. More...

Private Member Functions
	Configuration (const YAML::Node &node)
	Creates a subobject that has its root node at the given node. More...

Private Attributes
YAML::Node	root_node_
	the general_config.yaml contents - fully parsed More...

Constructor & Destructor Documentation

Configuration() [1/6]

smash::Configuration::Configuration ( const bf::path &  path )

explicit

Reads config.yaml from the specified path.

Parameters

[in]

path

The directory where the SMASH config files are located.

Definition at line 89 of file configuration.cc.

    : Configuration(path, "config.yaml") {}

Configuration() [2/6]

smash::Configuration::Configuration ( const bf::path &  path, const bf::path &  filename  )

explicit

Reads a YAML config file from the specified path.

Parameters

[in]	path	The directory where the SMASH config files are located.
[in]	filename	The filename (without path) of the YAML config file, in case you don't want the default "config.yaml".

Definition at line 93 of file configuration.cc.

                                                                       {
  const auto file_path = path / filename;
  if (!bf::exists(file_path)) {
    throw FileDoesNotExist("The configuration file was expected at '" +
                           file_path.native() +
                           "', but the file does not exist.");
  }
  if (has_crlf_line_ending(read_all(bf::ifstream((file_path))))) {
    throw std::runtime_error(
        "The configuration file has CR LF line endings. Please use LF "
        "line endings.");
  }
  try {
    root_node_ = YAML::LoadFile(file_path.native());
  } catch (YAML::ParserException &e) {
    if (e.msg == "illegal map value" || e.msg == "end of map not found") {
      const auto line = std::to_string(e.mark.line + 1);
      throw ParseError("YAML parse error at\n" + file_path.native() + ':' +
                       line + ": " + e.msg +
                       " (check that the indentation of map keys matches)");
    }
    throw;
  }
}

Here is the call graph for this function:

Configuration() [3/6]

smash::Configuration::Configuration ( const char *  yaml )

inlineexplicit

Unit tests can use this constructor to get a Configuration object from a built-in string.This function is only available to tests and should never be used/needed in actual SMASH code. The intention is to avoid creating a mock object for Configuration to test other classes of SMASH.

Definition at line 1056 of file configuration.h.

: root_node_(YAML::Load(yaml)) {}

Configuration() [4/6]

smash::Configuration::Configuration ( const Configuration &  )

default

If you want to copy this you're doing it wrong.

Configuration() [5/6]

smash::Configuration::Configuration ( Configuration &&  )

default

Moving is fine.

Configuration() [6/6]

smash::Configuration::Configuration ( const YAML::Node &  node )

inlineprivate

Creates a subobject that has its root node at the given node.

Note

This constructor is not explicit because it can be called only from inside Configuration and by making it explicit a return would require the copy constructor.

Definition at line 1211 of file configuration.h.

      : root_node_(node) {}

Member Function Documentation

operator=() [1/3]

Configuration& smash::Configuration::operator= ( const Configuration &  )

default

If you want to copy this you're doing it wrong.

operator=() [2/3]

Configuration& smash::Configuration::operator= ( Configuration &&  )

default

Moving is fine.

merge_yaml()

void smash::Configuration::merge_yaml

(

const std::string &

yaml

)

Merge the configuration in yaml into the existing tree.

The function parses the string in yaml into its internal tree representation. Then it merges the nodes from the new tree into the existing tree. The merge resolves conflicts by taking the value from yaml.

Parameters

[in]

yaml

A string with YAML (or JSON) content that is to be merged.

Definition at line 118 of file configuration.cc.

                                                    {
  try {
    root_node_ |= YAML::Load(yaml);
  } catch (YAML::ParserException &e) {
    if (e.msg == "illegal map value" || e.msg == "end of map not found") {
      const auto line = std::to_string(e.mark.line + 1);
      throw ParseError("YAML parse error in:\n" + yaml + "\nat line " + line +
                       ": " + e.msg +
                       " (check that the indentation of map keys matches)");
    }
    throw;
  }
}

Here is the caller graph for this function:

list_upmost_nodes()

std::vector< std::string > smash::Configuration::list_upmost_nodes

(

)

Lists all YAML::Nodes from the configuration setup.

Definition at line 132 of file configuration.cc.

                                                      {
  std::vector<std::string> r;
  for (auto i : root_node_) {
    r.emplace_back(i.first.Scalar());
  }
  return r;
}

take() [1/2]

Configuration::Value smash::Configuration::take

(

std::initializer_list< const char * >

keys

)

The default interface for SMASH to read configuration values.

The function returns the value at the specified keys and removes it from the Configuration object. Therefore, a subsequent call to take or has_value with the same keys returns an undefined value / false. By removing the value, the Configuration object keeps track which settings were never read.

Parameters

[in]

keys

You can pass an arbitrary number of keys inside curly braces, following the nesting structure in the config file. Example: Group: Key: Value Call string value = config.take({"Group", "Key"}); to read the value.

Returns

A proxy object that converts to the correct type automatically on assignment.

Definition at line 140 of file configuration.cc.

                                            {
  assert(keys.size() > 0);
  auto node = root_node_;
  auto keyIt = begin(keys);
  std::size_t i = 0;
  for (; i < keys.size() - 1; ++i, ++keyIt) {
    // Node::reset does what you might expect Node::operator= to do. But
    // operator= assigns a value to the node. So
    //   node = node[*keyIt]
    // leads to modification of the data structure, not simple traversal.
    node.reset(node[*keyIt]);
  }
  const auto r = node[*keyIt];
  node.remove(*keyIt);
  return {r, keys.begin()[keys.size() - 1]};
}

Here is the caller graph for this function:

take() [2/2]

template<typename T >

T smash::Configuration::take ( std::initializer_list< const char * >  keys, T  default_value  )

inline

See also

take

Definition at line 1109 of file configuration.h.

                                                                  {
    if (has_value(keys)) {
      return take(keys);
    }
    return default_value;
  }

Here is the call graph for this function:

read() [1/2]

Configuration::Value smash::Configuration::read

(

std::initializer_list< const char * >

keys

)

const

Additional interface for SMASH to read configuration values without removing them.

The function returns the value at the specified keys but does not remove it from the Configuration object. Semantically, this means the value was not used.

Parameters

[in]

keys

You can pass an arbitrary number of keys inside curly braces, following the nesting structure in the config file.

Returns

A proxy object that converts to the correct type automatically on assignment.

Definition at line 158 of file configuration.cc.

                                                  {
  return {find_node_at(root_node_, keys), keys.begin()[keys.size() - 1]};
}

Here is the call graph for this function:

Here is the caller graph for this function:

read() [2/2]

template<typename T >

T smash::Configuration::read ( std::initializer_list< const char * >  keys, T  default_value  )

inline

See also

read

Definition at line 1134 of file configuration.h.

                                                                  {
    if (has_value(keys)) {
      return read(keys);
    }
    return default_value;
  }

Here is the call graph for this function:

remove_all_but()

void smash::Configuration::remove_all_but

(

const std::string &

key

)

Removes all entries in the map except for key.

Parameters

[in]

key

The key of the map entry to keep.

Definition at line 163 of file configuration.cc.

                                                       {
  std::vector<std::string> to_remove;
  for (auto i : root_node_) {
    if (i.first.Scalar() != key) {
      to_remove.push_back(i.first.Scalar());
    }
  }
  for (auto i : to_remove) {
    root_node_.remove(i);
  }
}

Here is the caller graph for this function:

operator[]()

template<typename T >

Configuration smash::Configuration::operator[] ( T &&  key )

inline

Access to the YAML::Node behind the requested keys.

If you want to read a value use the read function above. Use the subscript operator if you want to assign a new value. The YAML::Node class will automatically convert the data you assign to a string representation suitable for the YAML file.

Parameters

[in]

key

The name of the key to be looked up

Returns

An opaque object that can be assigned to.

See also

take

read

Definition at line 1163 of file configuration.h.

                                    {
    return root_node_[std::forward<T>(key)];
  }

operator=() [3/3]

template<typename T >

Configuration& smash::Configuration::operator= ( T &&  value )

inline

Assignment overwrites the value of the current YAML node.

Parameters

[in]

value

An arbitrary value that yaml-cpp can convert into YAML representation. Any builtin type, strings, maps, and vectors can be used here.

Definition at line 1175 of file configuration.h.

                                      {
    root_node_ = std::forward<T>(value);
    return *this;
  }

has_value_including_empty()

bool smash::Configuration::has_value_including_empty

(

std::initializer_list< const char * >

keys

)

const

Returns if there is a (maybe empty) value behind the requested keys.

Parameters

[in]

keys

List of keys to be checked for

Definition at line 175 of file configuration.cc.

                                                  {
  const auto n = find_node_at(root_node_, keys);
  return n.IsDefined();
}

Here is the call graph for this function:

has_value()

bool smash::Configuration::has_value

(

std::initializer_list< const char * >

keys

)

const

Returns whether there is a non-empty value behind the requested keys.

Parameters

[in]

keys

List of keys to be checked for

Definition at line 181 of file configuration.cc.

                                                                          {
  const auto n = find_node_at(root_node_, keys);
  return n.IsDefined() && (!n.IsNull());
}

Here is the call graph for this function:

Here is the caller graph for this function:

unused_values_report()

std::string smash::Configuration::unused_values_report

(

)

const

Returns a string listing the key/value pairs that have not been taken yet.

Definition at line 186 of file configuration.cc.

                                                    {
  std::stringstream s;
  s << remove_empty_maps(root_node_);
  return s.str();
}

Here is the call graph for this function:

Here is the caller graph for this function:

to_string()

std::string smash::Configuration::to_string

(

)

const

Returns a YAML string of the current tree.

This differs from the above in that it does not remove empty maps.

Definition at line 192 of file configuration.cc.

                                         {
  std::stringstream s;
  s << root_node_;
  return s.str();
}

Here is the caller graph for this function:

Member Data Documentation

root_node_

YAML::Node smash::Configuration::root_node_

private

the general_config.yaml contents - fully parsed

Definition at line 1215 of file configuration.h.

---

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

• src/include/smash/configuration.h
• src/configuration.cc