configuration.cc

Go to the documentation of this file.

/*
 *
 *    Copyright (c) 2014-2019,2022,2024
 *      SMASH Team
 *
 *    GNU General Public License (GPLv3 or later)
 *
 */
 
#include "smash/configuration.h"
 
#include <cstdio>
#include <filesystem>
#include <fstream>
#include <numeric>
#include <string>
#include <vector>
 
#include "yaml-cpp/yaml.h"
 
#include "smash/forwarddeclarations.h"
#include "smash/input_keys.h"
#include "smash/inputfunctions.h"
#include "smash/logging.h"
#include "smash/stringfunctions.h"
 
namespace smash {
static constexpr int LConfiguration = LogArea::Configuration::id;
 
// internal helper functions
namespace {
void descend_one_existing_level(std::optional<YAML::Node> &node,
                                std::string_view key) {
  if (node) {
    for (const auto &section : node.value()) {
      /* Two remarks:
           1) The Node::operator[] creates an undefined node in the YAML tree if
              the node corresponding to the passed key does not exist and hence
              in this function, which descend one level which is expected to
              exist, we need to use it only if we are sure the node exists.
           2) Node::reset does what you might expect Node::operator= to do. But
              operator= assigns a value to the node and so
                 node = node[key]
              would lead to a further modification of the data structure and
              this function would not be simply traversal. Note that node and
              root_node_ point to the same memory and modification to the first
              would affect the second, too. */
      if (section.first.Scalar() == key) {
        node.value().reset(node.value()[key]);
        return;
      }
    }
    node = std::nullopt;
  }
}
 
YAML::Node remove_empty_maps(YAML::Node root) {
  if (root.IsMap()) {
    std::vector<std::string> to_remove(root.size());
    for (auto n : root) {
      remove_empty_maps(n.second);
      // If the node is an empty sequence, we do NOT remove it!
      if (n.second.IsMap() && n.second.size() == 0) {
        to_remove.emplace_back(n.first.Scalar());
      }
    }
    for (const auto &key : to_remove) {
      root.remove(key);
    }
  }
  return root;
}
 
YAML::Node operator|=(YAML::Node a, const YAML::Node &b) {
  if (b.IsMap()) {
    for (auto n0 : b) {
      a[n0.first.Scalar()] |= n0.second;
    }
  } else {
    a = b;
  }
  return a;
}
 
std::string join_quoted(std::vector<std::string_view> keys) {
  return std::accumulate(keys.begin(), keys.end(), std::string{"{"},
                         [](const std::string &ss, const std::string_view &s) {
                           return ss + ((ss.size() == 1) ? "\"" : ", \"") +
                                  std::string{s} +  // NOLINT(whitespace/braces)
                                  "\"";
                         }) +
         "}";
}
 
}  // unnamed namespace
 
// Default constructor
Configuration::Configuration(const std::filesystem::path &path)
    : Configuration(path, "config.yaml") {}
 
// Constructor checking for validity of input
Configuration::Configuration(const std::filesystem::path &path,
                             const std::filesystem::path &filename) {
  const auto file_path = path / filename;
  if (!std::filesystem::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(std::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;
  }
}
 
Configuration::Configuration(Configuration &&other)
    : root_node_(std::move(other.root_node_)),
      uncaught_exceptions_(std::move(other.uncaught_exceptions_)),
      existing_keys_already_taken_(
          std::move(other.existing_keys_already_taken_)) {
  other.root_node_.reset();
  other.uncaught_exceptions_ = 0;
  other.existing_keys_already_taken_.clear();
}
 
Configuration &Configuration::operator=(Configuration &&other) {
  // YAML does not offer != operator between nodes
  if (!(root_node_ == other.root_node_)) {
    root_node_ = std::move(other.root_node_);
    uncaught_exceptions_ = std::move(other.uncaught_exceptions_);
    existing_keys_already_taken_ =
        std::move(other.existing_keys_already_taken_);
    other.root_node_.reset();
    other.uncaught_exceptions_ = 0;
    other.existing_keys_already_taken_.clear();
  }
  return *this;
}
 
Configuration::~Configuration() noexcept(false) {
  // Make sure that stack unwinding is not taking place befor throwing
  if (std::uncaught_exceptions() == uncaught_exceptions_) {
    // In this scenario is fine to throw
    if (root_node_.size() != 0) {
      throw std::logic_error(
          "Configuration object destroyed with unused keys:\n" + to_string());
    }
  }
  /* If this destructor is called during stack unwinding, it is irrelevant
     that the Configuration has not be completely parsed. */
}
 
void Configuration::merge_yaml(const std::string &yaml) {
  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;
  }
}
 
std::vector<std::string> Configuration::list_upmost_nodes() {
  std::vector<std::string> r;
  r.reserve(root_node_.size());
  for (auto i : root_node_) {
    r.emplace_back(i.first.Scalar());
  }
  return r;
}
 
Configuration::Value Configuration::take(std::vector<std::string_view> labels) {
  assert(labels.size() > 0);
  /* Here we want to descend the YAML tree but not all the way to the last key,
     because we need the node associated to the previous to last key in order to
     remove the taken key. */
  auto last_key_it = labels.end() - 1;
  auto previous_to_last_node =
      find_existing_node({labels.begin(), last_key_it});
  auto to_be_returned{previous_to_last_node};
  descend_one_existing_level(to_be_returned, *last_key_it);
  if (!previous_to_last_node || !to_be_returned) {
    throw std::runtime_error(
        "Private Configuration::take method called with not existing key: " +
        join_quoted(labels) + ". This should not have happened.");
  }
  previous_to_last_node.value().remove(*last_key_it);
  root_node_ = remove_empty_maps(root_node_);
  if (const KeyLabels key_labels{labels.begin(), labels.end()};
      !did_key_exist_and_was_it_already_taken(key_labels)) {
    existing_keys_already_taken_.push_back(key_labels);
  }
  /* NOTE: The second argument in the returned statement to construct Value must
   * point to a string that is outliving the function scope and it would be
   * wrong to return e.g. something locally declared in the function. This is
   * because that argument is underneath of type 'const char* const' and, then,
   * if it was dangling after returning, it would be wrong to access it.
   */
  return {to_be_returned.value(), last_key_it->data()};
}
 
Configuration::Value Configuration::read(
    std::vector<std::string_view> labels) const {
  auto found_node = find_existing_node({labels.begin(), labels.end()});
  if (found_node) {
    // The same remark about the take return value applies here.
    return {found_node.value(), labels.back().data()};
  } else {
    throw std::runtime_error(
        "Private Configuration::read method called with not existing key: " +
        join_quoted(labels) + ". This should not have happened.");
  }
}
 
void Configuration::remove_all_entries_in_section_but_one(
    const std::string &key, KeyLabels section) {
  auto found_node = find_existing_node({section.begin(), section.end()});
  if (found_node) {
    std::vector<std::string> to_remove{};
    bool key_exists = false;
    for (auto i : found_node.value()) {
      if (i.first.Scalar() != key) {
        to_remove.push_back(i.first.Scalar());
      } else {
        key_exists = true;
      }
    }
    if (!key_exists) {
      std::string section_string{" section "};
      if (section.size() > 0) {
        section_string += join_quoted({section.begin(), section.end()}) + " ";
      } else {
        section_string = " top-level" + section_string;
      }
      throw std::invalid_argument("Attempt to remove all keys in" +
                                  section_string +
                                  "except not existing one: \"" + key + "\"");
    } else {
      for (auto i : to_remove) {
        found_node.value().remove(i);
      }
    }
  } else {
    throw std::invalid_argument(
        "Attempt to remove entries in not existing section: " +
        join_quoted({section.begin(), section.end()}));
  }
}
 
Configuration Configuration::extract_sub_configuration(
    KeyLabels section, Configuration::GetEmpty empty_if_not_existing) {
  // Same logic as in take method
  assert(section.size() > 0);
  auto last_key_it = section.end() - 1;
  auto previous_to_section_node =
      find_existing_node({section.begin(), last_key_it});
  auto sub_conf_root_node{previous_to_section_node};
  descend_one_existing_level(sub_conf_root_node, *last_key_it);
  if (!previous_to_section_node || !sub_conf_root_node) {
    if (empty_if_not_existing == Configuration::GetEmpty::Yes)
      return Configuration(YAML::Node{});
    else
      throw std::runtime_error("Attempt to extract not existing section " +
                               join_quoted({section.begin(), section.end()}));
  }
  /* Here sub_conf_root_node cannot be a nullopt, since if it was the function
     would have returned before and it cannot be that previous_to_section_node
     is nullopt and sub_conf_root_node is not */
  else if (sub_conf_root_node->IsNull() ||  // NOLINT[whitespace/newline]
           (sub_conf_root_node->IsMap() && sub_conf_root_node->size() == 0)) {
    // Here we put together the cases of a key without value or with
    // an empty map {} as value (no need at the moment to distinguish)
    throw std::runtime_error("Attempt to extract empty section " +
                             join_quoted({section.begin(), section.end()}));
  } else if (sub_conf_root_node->IsMap() && sub_conf_root_node->size() != 0) {
    Configuration sub_config{*sub_conf_root_node};
    previous_to_section_node->remove(*last_key_it);
    root_node_ = remove_empty_maps(root_node_);
    return sub_config;
  } else {  // sequence or scalar or any future new YAML type
    throw std::runtime_error("Tried to extract configuration section at " +
                             join_quoted({section.begin(), section.end()}) +
                             " to get a key value. Use take instead!");
  }
}
 
Configuration Configuration::extract_complete_sub_configuration(
    KeyLabels section, Configuration::GetEmpty empty_if_not_existing) {
  auto sub_configuration =
      extract_sub_configuration(section, empty_if_not_existing);
  sub_configuration.enclose_into_section(section);
  return sub_configuration;
}
 
void Configuration::enclose_into_section(KeyLabels section) {
  /* If the configuration is empty, force its root node to be a map. This is not
  done in the extract_sub_configuration method, which allows the possibility not
  to have a map node at root in the returned object, but here we
  know it will be a map. */
  if (root_node_.size() == 0) {
    root_node_ = YAML::Node(YAML::NodeType::Map);
  }
  /* Create a new configuration from an empty node adding there the nested-map
  structure. Then add the old root node to it and reset it to the new root one.
  Refer to the descend_one_existing_level comment to understand the usage of
  YAML::Node::operator[] and reset methods. */
  YAML::Node new_root_node{YAML::NodeType::Map};
  auto last_node = new_root_node;
  for (const auto &label : section) {
    last_node[label] = YAML::Node(YAML::NodeType::Map);
    last_node.reset(last_node[label]);
  }
  last_node = root_node_;
  root_node_.reset(new_root_node);
}
 
std::string Configuration::to_string() const {
  std::stringstream s;
  s << root_node_;
  return s.str();
}
 
std::optional<YAML::Node> Configuration::find_existing_node(
    std::vector<std::string_view> keys) const {
  /* Here we do not assert(keys.size()>0) and allow to pass in an empty vector,
     in which case the passed in YAML:Node is simply returned. This might happen
     e.g. in the take or extract_sub_configuration methods if called with a
     label of a key at top level of the configuration file. */
  std::optional<YAML::Node> node{root_node_};
  for (const auto &key : keys) {
    descend_one_existing_level(node, key);
  }
  return node;
}
 
YAML::Node Configuration::find_node_creating_it_if_not_existing(
    std::vector<std::string_view> keys) const {
  assert(keys.size() > 0);
  YAML::Node node{root_node_};
  for (const auto &key : keys) {
    // See comments in descend_one_existing_level function
    node.reset(node[key]);
  }
  return node;
}
 
// internal helper functions
namespace {
void fill_list_of_labels_per_key_in_yaml_tree(const YAML::Node &root_node,
                                              std::vector<KeyLabels> &list,
                                              KeyLabels &new_list_entry) {
  // Here sub_node is an iterator value, i.e. a key/value pair of nodes,
  // not a single YAML node (that's how YAML library works)
  for (const auto &sub_node : root_node) {
    new_list_entry.push_back(sub_node.first.as<std::string>());
    if (sub_node.second.IsMap())
      fill_list_of_labels_per_key_in_yaml_tree(sub_node.second, list,
                                               new_list_entry);
    else
      list.push_back(new_list_entry);
    new_list_entry.pop_back();
  }
}
 
auto get_list_of_labels_per_key_in_yaml_tree(const YAML::Node &root_node) {
  std::vector<KeyLabels> list{};
  KeyLabels aux{};
  fill_list_of_labels_per_key_in_yaml_tree(root_node, list, aux);
  return list;
}
 
template <typename T>
struct IsStdMap {
  static constexpr bool value = false;
};
 
template <typename MapKey, typename MapValue>
struct IsStdMap<std::map<MapKey, MapValue>> {
  static constexpr bool value = true;
};
 
auto collect_input_keys_taken_as_maps() {
  std::vector<KeyLabels> labels_of_keys_taken_as_map{};
  for (const auto &keys_variant : smash::InputKeys::list) {
    std::visit(
        [&labels_of_keys_taken_as_map](auto &&var) {
          /*
           * The following if checks if the SMASH input key has a map as value
           * and it deserves some explanation about the type extraction:
           *
           *   - arg -> object of type: std::cref(const Key<T>)
           *   - arg.get() -> object of type: const Key<T>&
           *   - decltype(arg.get()) ->  type: const Key<T>&
           *   - std::decay_t<decltype(arg.get())>::type -> type: Key<T>
           *   - std::decay_t<decltype(arg.get())>::type::value -> type: T
           */
          if constexpr (IsStdMap<typename std::decay_t<
                            decltype(var.get())>::type>::value)
            labels_of_keys_taken_as_map.push_back(var.get().labels());
        },
        keys_variant);
  }
  return labels_of_keys_taken_as_map;
}
 
void adjust_list_of_labels_dealing_with_keys_taken_as_maps(
    std::vector<KeyLabels> &list_of_input_key_labels) {
  const std::vector<KeyLabels> labels_of_keys_taken_as_map =
      collect_input_keys_taken_as_maps();
  for (const auto &labels : labels_of_keys_taken_as_map) {
    std::for_each(list_of_input_key_labels.begin(),
                  list_of_input_key_labels.end(),
                  [&labels](KeyLabels &labels_of_input_key) {
                    if (std::equal(labels.begin(), labels.end(),
                                   labels_of_input_key.begin(),
                                   labels_of_input_key.begin() + labels.size()))
                      labels_of_input_key = labels;
                  });
  }
  // The identical keys in list are now next to each other and we do
  // not need/want to sort the list before calling std::unique.
  list_of_input_key_labels.erase(std::unique(list_of_input_key_labels.begin(),
                                             list_of_input_key_labels.end()),
                                 list_of_input_key_labels.end());
}
 
Configuration::Is validate_key(const KeyLabels &labels) {
  auto key_ref_var_it = std::find_if(
      smash::InputKeys::list.begin(), smash::InputKeys::list.end(),
      [&labels](auto key) {
        return std::visit(
            [&labels](auto &&arg) { return arg.get().has_same_labels(labels); },
            key);
      });
  if (key_ref_var_it == smash::InputKeys::list.end()) {
    logg[LConfiguration].error("Key ", smash::quote(smash::join(labels, ": ")),
                               " is not a valid SMASH input key.");
    return Configuration::Is::Invalid;
  }
 
  smash::InputKeys::key_references_variant found_variant = *key_ref_var_it;
  const auto key_labels =
      std::visit([](auto &&var) { return static_cast<std::string>(var.get()); },
                 found_variant);
 
  if (std::visit([](auto &&var) { return !var.get().is_allowed(); },
                 found_variant)) {
    const auto v_removal = std::visit(
        [](auto &&var) { return var.get().removed_in(); }, found_variant);
    logg[LConfiguration].error("Key ", key_labels,
                               " has been removed in version ", v_removal,
                               " and it is not valid anymore.");
    return Configuration::Is::Invalid;
  }
  if (std::visit([](auto &&var) { return var.get().is_deprecated(); },
                 found_variant)) {
    const auto v_deprecation = std::visit(
        [](auto &&var) { return var.get().deprecated_in(); }, found_variant);
    logg[LConfiguration].warn(
        "Key ", key_labels, " has been deprecated in version ", v_deprecation);
    return Configuration::Is::Deprecated;
  } else {
    logg[LConfiguration].debug("Key ", key_labels, " is valid!");
    return Configuration::Is::Valid;
  }
}
 
void accumulate_validation(Configuration::Is &result_so_far,
                           Configuration::Is new_value) {
  switch (result_so_far) {
    case Configuration::Is::Invalid:
      break;
    case Configuration::Is::Deprecated:
      if (new_value != Configuration::Is::Valid) {
        result_so_far = new_value;
      }
      break;
    case Configuration::Is::Valid:
      result_so_far = new_value;
      break;
  }
}
 
}  // namespace
 
Configuration::Is Configuration::validate(bool full_validation) const {
  auto list = get_list_of_labels_per_key_in_yaml_tree(root_node_);
  adjust_list_of_labels_dealing_with_keys_taken_as_maps(list);
  Is validation_result{Is::Valid};
  for (const auto &key_labels : list) {
    Is key_state = validate_key(key_labels);
    if (full_validation) {
      accumulate_validation(validation_result, key_state);
    } else {
      if (key_state != Is::Valid)
        return key_state;
    }
  }
  return validation_result;
}
 
}  // namespace smash