#include <key.h>

template<typename default_type>
class smash::Key< default_type >

Object to store a YAML input file key together with metadata associated to it.

Note: The class is designed such that all keys can be marked as deprecated and as removed. However, it is not possible to mark a key as removed without having deprecated it before. A workaround is to deprecate and remove it in the same version, i.e. specifying the same version twice at construction.

Template Parameters

default_type Type of the key value. This must be a plain type, by that meaning have no cv-qualifier and not being any among the following types: array, pointer, function, or a mix of them.

Definition at line 158 of file key.h.

Classes
class	Default
	Wrapper class around a type with the capability to both store the type of default and its value, if any exists. More...

struct	WrongNumberOfVersions
	Thrown when too few or too many versions are passed to the constructor. More...

Public Types
using	validator_type = typename detail::KeyTraits< default_type >::validator_type

using	type = default_type
	Let the clients of this class have access to the key type. More...

Public Member Functions
	Key (const KeyLabels &labels, const KeyMetadata &versions, validator_type validator=detail::get_default_validator< default_type >())
	Construct a new `Key` object without default value. More...

	Key (const KeyLabels &labels, default_type value, const KeyMetadata &versions, validator_type validator=detail::get_default_validator< default_type >())
	Construct a new `Key` object with default value. More...

	Key (const KeyLabels &labels, DefaultType type_of_default, const KeyMetadata &versions, validator_type validator=detail::get_default_validator< default_type >())
	Construct a new `Key` object which is supposed to have a default value, which however depends on other keys and will remain unset. More...

default_type	default_value () const
	Get the default value of the key. More...

bool	has_dependent_default () const noexcept
	Ask whether the default value depends on other other keys. More...

Version	introduced_in () const noexcept
	Get the SMASH version in which the key has been introduced. More...

Version	deprecated_in () const
	Get the SMASH version in which the key has been deprecated. More...

Version	removed_in () const
	Get the SMASH version in which the key has been removed. More...

bool	is_deprecated () const noexcept
	Get whether the key is deprecated or not. More...

bool	is_allowed () const noexcept
	Get whether the key is still allowed or not. More...

bool	validate (const default_type &value) const noexcept
	Get whether the given key value is valid. More...

bool	has_same_labels (const KeyLabels &labels) const noexcept
	Check if given labels are the same as those of this object. More...

	operator std::string () const noexcept
	Converts a Key to a `std::string` using all labels. More...

std::string	as_yaml ([[maybe_unused]] std::optional< default_type > value=std::nullopt) const noexcept
	Build and return a YAML-formatted string in the compact form (using braces as single line). More...

std::string	as_yaml (std::string value) const noexcept
	Overload of the method taking a string as value. More...

const KeyLabels &	labels () const
	Method to access the `Key` labels. More...

Private Member Functions
	Key (const KeyLabels &labels, Default< default_type > value, const KeyMetadata &versions, validator_type validator)
	Private constructor of the Key object. More...

Private Attributes
Version	introduced_in_ {}
	SMASH version in which the key has been introduced. More...

std::optional< Version >	deprecated_in_ {}
	SMASH version in which the key has been deprecated, if any. More...

std::optional< Version >	removed_in_ {}
	SMASH version in which the key has been removed, if any. More...

Default< default_type >	default_ {}
	Key default value. More...

KeyLabels	labels_ {}
	The label(s) identifying the key in the YAML input file. More...

validator_type	validator_ {detail::get_default_validator<default_type>()}
	The functor to validate key values. More...

Member Typedef Documentation

◆ validator_type

template<typename default_type >

using smash::Key< default_type >::validator_type = typename detail::KeyTraits<default_type>::validator_type

See also: detail::KeyTraits<T>::validator_type

Definition at line 180 of file key.h.

◆ type

template<typename default_type >

using smash::Key< default_type >::type = default_type

Let the clients of this class have access to the key type.

Definition at line 242 of file key.h.

Constructor & Destructor Documentation

◆ Key() [1/4]

template<typename default_type >

smash::Key< default_type >::Key	(	const KeyLabels &	labels,
		const KeyMetadata &	versions,
		validator_type	validator = `detail::get_default_validator<default_type>()`
	)

inlineexplicit

Construct a new Key object without default value.

Parameters

[in]	labels	The label(s) identifying the key in the YAML input file.
[in]	versions	A list of one, two or three version numbers identifying the versions in which the key has been introduced, deprecated and removed, respectively.
[in]	validator	An optional functor that takes a default_type parameters and returns a bool variable.

Exceptions

WrongNumberOfVersions If versions has the wrong size.

Definition at line 195 of file key.h.

198 : Key{labels, Default<default_type>{}, versions, validator} {}

smash::Key::Key

Key(const KeyLabels &labels, const KeyMetadata &versions, validator_type validator=detail::get_default_validator< default_type >())

Construct a new Key object without default value.

Definition: key.h:195

smash::Key::labels

const KeyLabels & labels() const

Method to access the Key labels.

Definition: key.h:397

◆ Key() [2/4]

template<typename default_type >

smash::Key< default_type >::Key	(	const KeyLabels &	labels,
		default_type	value,
		const KeyMetadata &	versions,
		validator_type	validator = `detail::get_default_validator<default_type>()`
	)

inline

Construct a new Key object with default value.

Parameters

[in]	labels	The label(s) identifying the key in the YAML input file.
[in]	value	The key default value.
[in]	versions	A list of one, two or three version numbers identifying the versions in which the key has been introduced, deprecated and removed, respectively.
[in]	validator	An optional functor that takes a default_type parameters and returns a bool variable.

Exceptions

WrongNumberOfVersions	If `versions` has the wrong size.
std::invalid_argument	If `validator(value)` returns `false` .

Definition at line 214 of file key.h.

216 : Key{labels, Default<default_type>{value}, versions, validator} {}

◆ Key() [3/4]

template<typename default_type >

smash::Key< default_type >::Key	(	const KeyLabels &	labels,
		DefaultType	type_of_default,
		const KeyMetadata &	versions,
		validator_type	validator = `detail::get_default_validator<default_type>()`
	)

inline

Construct a new Key object which is supposed to have a default value, which however depends on other keys and will remain unset.

Parameters

[in]	labels	The label(s) identifying the key in the YAML input file.
[in]	type_of_default	The type of default value.
[in]	versions	A list of one, two or three version numbers identifying the versions in which the key has been introduced, deprecated and removed, respectively.
[in]	validator	An optional functor that takes a default_type parameters and returns a bool variable.

Exceptions

WrongNumberOfVersions	If `versions` has the wrong size.
std::logic_error	If `type` is not `DefaultType::Dependent` .

Definition at line 233 of file key.h.

236 : Key{labels, Default<default_type>{type_of_default}, versions,

237 validator} {}

◆ Key() [4/4]

template<typename default_type >

smash::Key< default_type >::Key	(	const KeyLabels &	labels,
		Default< default_type >	value,
		const KeyMetadata &	versions,
		validator_type	validator
	)

inlineprivate

Private constructor of the Key object.

This is meant to do the real construction, while the other public constructors just delegate to this one. This is possible because this constructor takes a Default argument and the other construct one to delegate construction.

See also: public constructor documentation for the parameters description.

Definition at line 490 of file key.h.

       : 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.");
     }
   }

Member Function Documentation

◆ default_value()

template<typename default_type >

default_type smash::Key< default_type >::default_value ( ) const

inline

Get the default value of the key.

Returns: A default_type variable.

Exceptions

std::bad_optional_access If the key has no default value.

Definition at line 251 of file key.h.

251 { return default_.value(); }

smash::Key::Default::value

T value() const

Retrieve the default value stored in the object.

Definition: key.h:457

◆ has_dependent_default()

template<typename default_type >

bool smash::Key< default_type >::has_dependent_default ( ) const

inlinenoexcept

Ask whether the default value depends on other other keys.

Returns: true if this is the case,; false if the default value is known or the key is mandatory.

Definition at line 259 of file key.h.

                                               {
     return default_.is_dependent();
   }

◆ introduced_in()

template<typename default_type >

Version smash::Key< default_type >::introduced_in ( ) const

inlinenoexcept

Get the SMASH version in which the key has been introduced.

Returns: A Version variable.

Definition at line 268 of file key.h.

268 { return introduced_in_; }

◆ deprecated_in()

template<typename default_type >

Version smash::Key< default_type >::deprecated_in ( ) const

inline

Get the SMASH version in which the key has been deprecated.

Returns: A Version variable.

Exceptions

std::bad_optional_access If the key is not deprecated.

Definition at line 277 of file key.h.

277 { return deprecated_in_.value(); }

◆ removed_in()

template<typename default_type >

Version smash::Key< default_type >::removed_in ( ) const

inline

Get the SMASH version in which the key has been removed.

Returns: A Version variable.

Exceptions

std::bad_optional_access If the key is still allowed.

Definition at line 286 of file key.h.

286 { return removed_in_.value(); }

◆ is_deprecated()

template<typename default_type >

bool smash::Key< default_type >::is_deprecated ( ) const

inlinenoexcept

Get whether the key is deprecated or not.

Returns: true if the key is deprecated, false otherwise.

Definition at line 293 of file key.h.

293 { return deprecated_in_.has_value(); }

◆ is_allowed()

template<typename default_type >

bool smash::Key< default_type >::is_allowed ( ) const

inlinenoexcept

Get whether the key is still allowed or not.

Returns: true if the key is allowed, false otherwise.

Definition at line 300 of file key.h.

300 { return !removed_in_.has_value(); }

◆ validate()

template<typename default_type >

bool smash::Key< default_type >::validate ( const default_type & value ) const

inlinenoexcept

Get whether the given key value is valid.

Note: Since at the moment not-noexcept validators are accepted from this class, but we still want the noexcept specification for this method, we wrap the validation in a try block and give a non-fatal error if an exception is thrown by the validator. Note that the not-exceptional branch should always be run and, hence, no performance impact should occur.

Parameters

[in] value The value to be validated.

Returns: true if the given value is valid,; false otherwise.

Definition at line 316 of file key.h.

                                                           {
     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;
     }
   }

◆ has_same_labels()

template<typename default_type >

bool smash::Key< default_type >::has_same_labels ( const KeyLabels & labels ) const

inlinenoexcept

Check if given labels are the same as those of this object.

Parameters

[in] labels Given labels to be checked against.

Returns: true if all labels match in the given order,; false otherwise.

Definition at line 336 of file key.h.

                                                                {
     return std::equal(std::begin(labels_), std::end(labels_),
                       std::begin(labels), std::end(labels));
   }

◆ operator std::string()

template<typename default_type >

smash::Key< default_type >::operator std::string ( ) const

inlineexplicitnoexcept

Converts a Key to a std::string using all labels.

Returns: std::string with labels concatenated with :␣ (colon-space) and quotes all around.

Definition at line 347 of file key.h.

                                                {
     return smash::quote(smash::join(labels_, ": "));
   }

◆ as_yaml() [1/2]

template<typename default_type >

std::string smash::Key< default_type >::as_yaml ( [[maybe_unused] ] std::optional< default_type > value = std::nullopt ) const

inlinenoexcept

Build and return a YAML-formatted string in the compact form (using braces as single line).

Parameters

[in] value An std::optional value of the Key type. If a value is passed, this is added to the resulting string if its type is streamable using the << operator. If no value is passed and the key has a streamable default, this is used.

Returns: std::string with labels formatted in a compact YAML format.

Definition at line 362 of file key.h.

                                                      {
     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());
   }

◆ as_yaml() [2/2]

template<typename default_type >

std::string smash::Key< default_type >::as_yaml ( std::string value ) const

inlinenoexcept

Overload of the method taking a string as value.

This can be useful for non streamable types e.g. in tests.

Note: The passed value is not quoted and it is responsibility of the caller to properly quote it, if needed. This enables setting e.g. YAML maps as value.

See also: as_yaml

Definition at line 385 of file key.h.

                                                     {
     std::stringstream result{};
     result << "{" << smash::join(labels_, ": {") << ": " << value
            << smash::join(std::vector<std::string>(labels_.size(), "}"), "");
     return result.str();
   }

◆ labels()

template<typename default_type >

const KeyLabels& smash::Key< default_type >::labels ( ) const

inline

Method to access the Key labels.

Returns: A constant reference to the labels member for read-only access.

Definition at line 397 of file key.h.

397 { return labels_; }

Member Data Documentation

◆ introduced_in_

template<typename default_type >

Version smash::Key< default_type >::introduced_in_ {}

private

SMASH version in which the key has been introduced.

Definition at line 540 of file key.h.

◆ deprecated_in_

template<typename default_type >

std::optional<Version> smash::Key< default_type >::deprecated_in_ {}

private

SMASH version in which the key has been deprecated, if any.

Definition at line 542 of file key.h.

◆ removed_in_

template<typename default_type >

std::optional<Version> smash::Key< default_type >::removed_in_ {}

private

SMASH version in which the key has been removed, if any.

Definition at line 544 of file key.h.

◆ default_

template<typename default_type >

Default<default_type> smash::Key< default_type >::default_ {}

private

Key default value.

Definition at line 546 of file key.h.

◆ labels_

template<typename default_type >

KeyLabels smash::Key< default_type >::labels_ {}

private

The label(s) identifying the key in the YAML input file.

Definition at line 548 of file key.h.

◆ validator_

template<typename default_type >

validator_type smash::Key< default_type >::validator_ {detail::get_default_validator<default_type>()}

private

The functor to validate key values.

Definition at line 550 of file key.h.

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

src/include/smash/key.h

template<typename default_type> class smash::Key< default_type >

Classes

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Member Typedef Documentation

◆ validator_type

◆ type

Constructor & Destructor Documentation

◆ Key() [1/4]

◆ Key() [2/4]

◆ Key() [3/4]

◆ Key() [4/4]

Member Function Documentation

◆ default_value()

◆ has_dependent_default()

◆ introduced_in()

◆ deprecated_in()

◆ removed_in()

◆ is_deprecated()

◆ is_allowed()

◆ validate()

◆ has_same_labels()

◆ operator std::string()

◆ as_yaml() [1/2]

◆ as_yaml() [2/2]

◆ labels()

Member Data Documentation

◆ introduced_in_

◆ deprecated_in_

◆ removed_in_

◆ default_

◆ labels_

◆ validator_

template<typename default_type>
class smash::Key< default_type >