key.h

Go to the documentation of this file.

/*
 *
 *    Copyright (c) 2024-2025
 *      SMASH Team
 *
 *    GNU General Public License (GPLv3 or later)
 *
 */
 
#ifndef SRC_INCLUDE_SMASH_KEY_H_
#define SRC_INCLUDE_SMASH_KEY_H_
 
#include <cassert>
#include <functional>
#include <optional>
#include <sstream>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
 
#include "logging.h"
#include "stringfunctions.h"
#include "traits.h"
 
namespace smash {
 
using Version = std::string;
 
using KeyMetadata = std::initializer_list<std::string_view>;
 
using KeyLabels = std::vector<std::string>;
 
inline KeyLabels operator+(const KeyLabels& lhs, std::string_view rhs) {
  if (lhs.empty()) {
    return KeyLabels{std::string{rhs}};
  } else {
    KeyLabels result{lhs};
    result.push_back(std::string{rhs});
    return result;
  }
}
 
inline KeyLabels operator+(KeyLabels&& lhs, std::string_view rhs) {
  if (lhs.empty()) {
    return KeyLabels{std::string{rhs}};
  } else {
    lhs.push_back(std::string{rhs});
    return std::move(lhs);  // See https://stackoverflow.com/a/14857144
  }
}
 
enum class DefaultType {
  Null,
  Value,
  Dependent
};
 
namespace detail {
 
template <typename T>
struct KeyTraits {
  using validator_type = std::function<bool(const T&)>;
};
 
template <typename T>
const typename KeyTraits<T>::validator_type& get_default_validator() noexcept {
  static const typename KeyTraits<T>::validator_type always_true =
      [](const T&) noexcept { return true; };
  return always_true;
}
 
}  // namespace detail
 
template <typename default_type>
class Key {
  static_assert(!std::is_const_v<default_type>);
  static_assert(!std::is_volatile_v<default_type>);
  static_assert(!std::is_reference_v<default_type>);
  static_assert(!std::is_pointer_v<default_type>);
  static_assert(!std::is_array_v<default_type>);
  static_assert(!std::is_function_v<default_type>);
  static_assert(!std::is_member_object_pointer_v<default_type>);
  static_assert(!std::is_member_function_pointer_v<default_type>);
 
 public:
  struct WrongNumberOfVersions : public std::runtime_error {
    using std::runtime_error::runtime_error;
  };
 
  using validator_type =
      typename detail::KeyTraits<default_type>::validator_type;
 
  explicit Key(
      const KeyLabels& labels, const KeyMetadata& versions,
      validator_type validator = detail::get_default_validator<default_type>())
      : Key{labels, Default<default_type>{}, versions, validator} {}
 
  Key(const KeyLabels& labels, default_type value, const KeyMetadata& versions,
      validator_type validator = detail::get_default_validator<default_type>())
      : Key{labels, Default<default_type>{value}, versions, validator} {}
 
  Key(const KeyLabels& labels, DefaultType type_of_default,
      const KeyMetadata& versions,
      validator_type validator = detail::get_default_validator<default_type>())
      : Key{labels, Default<default_type>{type_of_default}, versions,
            validator} {}
 
  using type = default_type;
 
  default_type default_value() const { return default_.value(); }
 
  bool has_dependent_default() const noexcept {
    return default_.is_dependent();
  }
 
  Version introduced_in() const noexcept { return introduced_in_; }
 
  Version deprecated_in() const { return deprecated_in_.value(); }
 
  Version removed_in() const { return removed_in_.value(); }
 
  bool is_deprecated() const noexcept { return deprecated_in_.has_value(); }
 
  bool is_allowed() const noexcept { return !removed_in_.has_value(); }
 
  bool validate(const default_type& value) const noexcept {
    try {
      return validator_(value);
    } catch (...) {
      logg[LogArea::Configuration::id].error(
          "Validator of key " + static_cast<std::string>(*this) +
          " threw an exception when validating key value.\nThis should not "
          "happen. Considering value invalid.");
      return false;
    }
  }
 
  bool has_same_labels(const KeyLabels& labels) const noexcept {
    return std::equal(std::begin(labels_), std::end(labels_),
                      std::begin(labels), std::end(labels));
  }
 
  explicit operator std::string() const noexcept {
    return smash::quote(smash::join(labels_, ": "));
  }
 
  std::string as_yaml([[maybe_unused]] std::optional<default_type> value =
                          std::nullopt) const noexcept {
    std::stringstream value_as_string{};
    if constexpr (is_writable_to_stream_v<std::stringstream, default_type>) {
      if (value) {
        value_as_string << *value;
      } else if (default_.type_ == DefaultType::Value) {
        value_as_string << default_value();
      }
    }
    return as_yaml(value_as_string.str());
  }
 
  std::string as_yaml(std::string value) const noexcept {
    std::stringstream result{};
    result << "{" << smash::join(labels_, ": {") << ": " << value
           << smash::join(std::vector<std::string>(labels_.size(), "}"), "");
    return result.str();
  }
 
  const KeyLabels& labels() const { return labels_; }
 
 private:
  template <typename T>
  class Default {
   public:
    Default() : type_{DefaultType::Null} {}
    explicit Default(T in) : value_{std::move(in)} {}
    explicit Default(DefaultType type) : type_{type} {
      if (type != DefaultType::Dependent) {
        throw std::logic_error("Default constructor used with invalid type!");
      }
    }
 
    T value() const { return value_.value(); }
 
    bool is_dependent() const noexcept {
      return type_ == DefaultType::Dependent;
    }
 
   private:
    DefaultType type_ = DefaultType::Value;
    std::optional<T> value_ = std::nullopt;
    // Make nested class friend of enclosing one. This class is anyhow an
    // implementation detail and part of Key.
    friend class Key<T>;
  };
 
  Key(const KeyLabels& labels, Default<default_type> value,
      const KeyMetadata& versions, validator_type validator)
      : default_{std::move(value)},
        labels_{labels.begin(), labels.end()},
        validator_{std::move(validator)} {
    /*
     * The following switch statement is a compact way to initialize the
     * three version member variables without repetition and lots of logic
     * clauses. The versions variable can have 1, 2 or 3 entries. The use of
     * the iterator is needed, since std::initializer_list has no access
     * operator.
     */
    switch (auto it = versions.end(); versions.size()) {
      case 3:
        removed_in_ = *(--it);
        [[fallthrough]];
      case 2:
        deprecated_in_ = *(--it);
        [[fallthrough]];
      case 1:
        introduced_in_ = *(--it);
        break;
      default:
        throw WrongNumberOfVersions(
            "Key constructor needs one, two or three version numbers.");
    }
    /* Ensure validator_ is set, which is usually the case unless in scenarios
     * that are particularly nasty to debug (e.g. calling this constructor from
     * a static/global object using a static/global validator and hence hitting
     * the undefined order of static initialisation).
     *
     * NOTE: Do NOT throw from here. For non-local static keys we prefer to
     * assign the canonical default validator when an empty functor is provided;
     * throwing during static initialization can cause termination or even
     * undefined behavior.
     */
    if (!validator_) {
      logg[LogArea::Configuration::id].error(
          "Empty validator used at Key construction time.\nThis should not "
          "happen. Using default validator instead.");
      validator_ = detail::get_default_validator<default_type>();
    }
    if (default_.value_ && validator_(*(default_.value_)) == false) {
      throw std::logic_error(
          "Key " + static_cast<std::string>(*this) +
          " has been declared with an invalid default value.");
    }
  }
 
  Version introduced_in_{};
  std::optional<Version> deprecated_in_{};
  std::optional<Version> removed_in_{};
  Default<default_type> default_{};
  KeyLabels labels_{};
  validator_type validator_{detail::get_default_validator<default_type>()};
};
 
}  // namespace smash
 
#endif  // SRC_INCLUDE_SMASH_KEY_H_