yaml_config::YamlConfig Class Reference

Table of Contents

• Detailed Description
• Classes
• Public Types
• Public Member Functions
• Member Typedef Documentation
• const_iterator
• Exception
• ParseException
• Member Enumeration Documentation
• Mode
• Member Function Documentation
• As() [1/3]
• As() [2/3]
• As() [3/3]
• begin()
• CheckArray()
• CheckArrayOrNull()
• CheckNotMissing()
• CheckObject()
• CheckObjectOrArrayOrNull()
• CheckObjectOrNull()
• CheckString()
• end()
• GetSize()
• HasMember()
• operator[]() [1/2]
• operator[]() [2/2]

#include <userver/yaml_config/yaml_config.hpp>

Detailed Description

Datatype that represents YAML with substituted variables.

If YAML has value that starts with an $, then such value is treated as a variable from config_vars. For example if config_vars contains variable: 42 and the YAML is following:

  auto node = formats::yaml::FromString(R"(
    some_element:
        some: $variable
  )");
  auto vars = formats::yaml::FromString("variable: 42");
 
  yaml_config::YamlConfig yaml(std::move(node), vars);
  EXPECT_EQ(yaml["some_element"]["some"].As<int>(), 42);

Then the result of yaml["some_element"]["some"].As<int>() is 42.

If YAML key ends on '#env' and the mode is YamlConfig::Mode::kEnvAllowed, then the value of the key is searched in environment variables of the process and returned as a value. For example:

  auto node = formats::yaml::FromString(R"(
    some_element:
        some#env: ENV_VARIABLE_NAME
  )");
 
  // NOLINTNEXTLINE(concurrency-mt-unsafe)
  ::setenv("ENV_VARIABLE_NAME", "100", 1);
 
  yaml_config::YamlConfig yaml(std::move(node), {},
                               yaml_config::YamlConfig::Mode::kEnvAllowed);
  EXPECT_EQ(yaml["some_element"]["some"].As<int>(), 100);

If YAML key ends on '#fallback', then the value of the key is used as a fallback for environment and $ variables. For example for the following YAML with YamlConfig::Mode::kEnvAllowed:

# yaml
some_element:
    some: $variable
    some#env: SOME_ENV_VARIABLE
    some#fallback: 100500

The result of yaml["some_element"]["some"].As<int>() is the value of variable from config_vars if it exists; otherwise the value is the contents of the environment variable SOME_ENV_VARIABLE if it exists; otherwise the value if 100500, from the fallback.

Another example:

# yaml
some_element:
    some#env: ENV_NAME
    some#fallback: 5

With YamlConfig::Mode::kEnvAllowed the result of yaml["some_element"]["value"].As<int>() is the value of ENV_NAME environment variable if it exists; otherwise it is 5.

Warning

YamlConfig::Mode::kEnvAllowed should be used only on configs that come from trusted environments. Otherwise, an attacker could create a config with #env and read any of your environment variables, including variables that contain passwords and other sensitive data.

Definition at line 61 of file yaml_config.hpp.

Inheritance diagram for yaml_config::YamlConfig:

Classes
struct	DefaultConstructed
struct	IterTraits

Public Types
enum class	Mode {   kSecure ,   kEnvAllowed }
using	const_iterator = Iterator<IterTraits>
using	Exception = yaml_config::Exception
using	ParseException = yaml_config::ParseException

Public Member Functions
	YamlConfig (formats::yaml::Value yaml, formats::yaml::Value config_vars, Mode mode=Mode::kSecure)
	YamlConfig = config + config_vars.
const formats::yaml::Value &	Yaml () const
	Get the plain Yaml without substitutions. It may contain raw references.
YamlConfig	operator[] (std::string_view key) const
	Access member by key for read.
YamlConfig	operator[] (size_t index) const
	Access member by index for read.
std::size_t	GetSize () const
	Returns array size or object members count.
bool	IsMissing () const noexcept
	Returns true if *this holds nothing. When IsMissing() returns true any attempt to get the actual value or iterate over *this will throw MemberMissingException.
bool	IsNull () const noexcept
	Returns true if *this holds 'null'.
bool	IsBool () const noexcept
	Returns true if *this is convertible to bool.
bool	IsInt () const noexcept
	Returns true if *this is convertible to int.
bool	IsInt64 () const noexcept
	Returns true if *this is convertible to int64_t.
bool	IsUInt64 () const noexcept
	Returns true if *this is convertible to uint64_t.
bool	IsDouble () const noexcept
	Returns true if *this is convertible to double.
bool	IsString () const noexcept
	Returns true if *this is convertible to std::string.
bool	IsArray () const noexcept
	Returns true if *this is an array (Type::kArray).
bool	IsObject () const noexcept
	Returns true if *this is a map (Type::kObject).
void	CheckNotMissing () const
void	CheckArray () const
void	CheckArrayOrNull () const
void	CheckObjectOrNull () const
void	CheckObject () const
void	CheckString () const
void	CheckObjectOrArrayOrNull () const
template<typename T >
auto	As () const
	Returns value of *this converted to T.
template<typename T , typename First , typename... Rest>
auto	As (First &&default_arg, Rest &&... more_default_args) const
	Returns value of *this converted to T or T(args) if this->IsMissing().
template<typename T >
auto	As (DefaultConstructed) const
	Returns value of *this converted to T or T() if this->IsMissing().
bool	HasMember (std::string_view key) const
	Returns true if *this holds a key.
std::string	GetPath () const
	Returns full path to this value.
const_iterator	begin () const
	Returns an iterator to the beginning of the held array or map.
const_iterator	end () const
	Returns an iterator to the end of the held array or map.

Member Typedef Documentation

const_iterator

using yaml_config::YamlConfig::const_iterator = Iterator<IterTraits>

Definition at line 75 of file yaml_config.hpp.

Exception

using yaml_config::YamlConfig::Exception = yaml_config::Exception

Definition at line 76 of file yaml_config.hpp.

ParseException

using yaml_config::YamlConfig::ParseException = yaml_config::ParseException

Definition at line 77 of file yaml_config.hpp.

Member Enumeration Documentation

Mode

enum class yaml_config::YamlConfig::Mode

strong

Enumerator
kEnvAllowed	< secure mode, without reading environment variables

Definition at line 70 of file yaml_config.hpp.

Member Function Documentation

As() [1/3]

template<typename T >

auto yaml_config::YamlConfig::As

(

)

const

Returns value of *this converted to T.

Exceptions

Anything

derived from std::exception.

Examples

components/component_sample_test.cpp, samples/grpc_service/grpc_service.cpp, and samples/postgres_auth/auth_bearer.cpp.

Definition at line 203 of file yaml_config.hpp.

As() [2/3]

template<typename T >

auto yaml_config::YamlConfig::As

(

YamlConfig::DefaultConstructed

)

const

Returns value of *this converted to T or T() if this->IsMissing().

Exceptions

Anything

derived from std::exception.

Note

Use as value.As<T>({})

Definition at line 237 of file yaml_config.hpp.

As() [3/3]

template<typename T , typename First , typename... Rest>

auto yaml_config::YamlConfig::As	(	First &&	default_arg,
		Rest &&...	more_default_args ) const

Returns value of *this converted to T or T(args) if this->IsMissing().

Exceptions

Anything

derived from std::exception.

Definition at line 226 of file yaml_config.hpp.

begin()

const_iterator yaml_config::YamlConfig::begin

(

)

const

Returns an iterator to the beginning of the held array or map.

Exceptions

TypeMismatchException

is the value of *this is not a map, array or Null.

CheckArray()

void yaml_config::YamlConfig::CheckArray

(

)

const

Exceptions

MemberMissingException

if *this is not an array.

CheckArrayOrNull()

void yaml_config::YamlConfig::CheckArrayOrNull

(

)

const

Exceptions

MemberMissingException

if *this is not an array or Null.

CheckNotMissing()

void yaml_config::YamlConfig::CheckNotMissing

(

)

const

Exceptions

MemberMissingException

if this->IsMissing().

CheckObject()

void yaml_config::YamlConfig::CheckObject

(

)

const

Exceptions

TypeMismatchException

if *this is not a map.

CheckObjectOrArrayOrNull()

void yaml_config::YamlConfig::CheckObjectOrArrayOrNull

(

)

const

Exceptions

TypeMismatchException

if *this is not a map, array or Null.

CheckObjectOrNull()

void yaml_config::YamlConfig::CheckObjectOrNull

(

)

const

Exceptions

TypeMismatchException

if *this is not a map or Null.

CheckString()

void yaml_config::YamlConfig::CheckString

(

)

const

Exceptions

TypeMismatchException

if *this is not convertible to std::string.

end()

const_iterator yaml_config::YamlConfig::end

(

)

const

Returns an iterator to the end of the held array or map.

Exceptions

TypeMismatchException

is the value of *this is not a map, array or Null.

GetSize()

std::size_t yaml_config::YamlConfig::GetSize

(

)

const

Returns array size or object members count.

Exceptions

TypeMismatchException

if not array or object value.

HasMember()

bool yaml_config::YamlConfig::HasMember

(

std::string_view

key

)

const

Returns true if *this holds a key.

Exceptions

Nothing.

operator[]() [1/2]

YamlConfig yaml_config::YamlConfig::operator[]

(

size_t

index

)

const

Access member by index for read.

Exceptions

TypeMismatchException

if value is not missing and is not array.

operator[]() [2/2]

YamlConfig yaml_config::YamlConfig::operator[]

(

std::string_view

key

)

const

Access member by key for read.

Exceptions

TypeMismatchException

if value is not missing and is not object.

---

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

• userver/yaml_config/yaml_config.hpp