userver: yaml_config::YamlConfig Class Reference
Loading...
Searching...
No Matches
yaml_config::YamlConfig Class Reference

#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), {},
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::ValueYaml () 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

◆ Exception

◆ ParseException

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
Anythingderived 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
Anythingderived 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
Anythingderived 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
TypeMismatchExceptionis the value of *this is not a map, array or Null.

◆ CheckArray()

void yaml_config::YamlConfig::CheckArray ( ) const
Exceptions
MemberMissingExceptionif *this is not an array.

◆ CheckArrayOrNull()

void yaml_config::YamlConfig::CheckArrayOrNull ( ) const
Exceptions
MemberMissingExceptionif *this is not an array or Null.

◆ CheckNotMissing()

void yaml_config::YamlConfig::CheckNotMissing ( ) const
Exceptions
MemberMissingExceptionif this->IsMissing().

◆ CheckObject()

void yaml_config::YamlConfig::CheckObject ( ) const
Exceptions
TypeMismatchExceptionif *this is not a map.

◆ CheckObjectOrArrayOrNull()

void yaml_config::YamlConfig::CheckObjectOrArrayOrNull ( ) const
Exceptions
TypeMismatchExceptionif *this is not a map, array or Null.

◆ CheckObjectOrNull()

void yaml_config::YamlConfig::CheckObjectOrNull ( ) const
Exceptions
TypeMismatchExceptionif *this is not a map or Null.

◆ CheckString()

void yaml_config::YamlConfig::CheckString ( ) const
Exceptions
TypeMismatchExceptionif *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
TypeMismatchExceptionis 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
TypeMismatchExceptionif 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
TypeMismatchExceptionif 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
TypeMismatchExceptionif value is not missing and is not object.

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