#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 104 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	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)
	Construct a new `Key` object without default value. More...

	Key (const KeyLabels &labels, default_type value, const KeyMetadata &versions)
	Construct a new `Key` object with default value. More...

	Key (const KeyLabels &labels, DefaultType type_of_default, const KeyMetadata &versions)
	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	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 (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)
	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...

Member Typedef Documentation

◆ 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 168 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
	)

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.

Definition at line 131 of file key.h.

132 : Key{labels, Default<default_type>{}, versions} {}

smash::Key::Key

Key(const KeyLabels &labels, const KeyMetadata &versions)

Construct a new Key object without default value.

Definition: key.h:131

smash::Key::labels

const KeyLabels & labels() const

Method to access the Key labels.

Definition: key.h:297

◆ Key() [2/4]

template<typename default_type >

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

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.

Exceptions

WrongNumberOfVersions If versions has the wrong size.

Definition at line 145 of file key.h.

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

◆ Key() [3/4]

template<typename default_type >

smash::Key< default_type >::Key	(	const KeyLabels &	labels,
		DefaultType	type_of_default,
		const KeyMetadata &	versions
	)

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.

Exceptions

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

Definition at line 161 of file key.h.

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

◆ Key() [4/4]

template<typename default_type >

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

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 390 of file key.h.

       : default_{std::move(value)}, labels_{labels.begin(), labels.end()} {
     /*
      * 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.");
     }
   }

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 177 of file key.h.

177 { return default_.value(); }

smash::Key::Default::value

T value() const

Retrieve the default value stored in the object.

Definition: key.h:357

◆ 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 185 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 194 of file key.h.

194 { 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 203 of file key.h.

203 { 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 212 of file key.h.

212 { 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 219 of file key.h.

219 { 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 226 of file key.h.

226 { return !removed_in_.has_value(); }

◆ 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 236 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 247 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 ( 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 262 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 285 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 297 of file key.h.

297 { 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 417 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 419 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 421 of file key.h.

◆ default_

template<typename default_type >

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

private

Key default value.

Definition at line 423 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 425 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

◆ 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()

◆ 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_

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