#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);
    EXPECT_EQ(yaml["some_element"]["some"].GetPath(), "some_element.some");

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 or YamlConfig::Mode::kEnvAndFileAllowed, 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 #file and the mode is YamlConfig::Mode::kEnvAndFileAllowed, then the value of the key is the content of specified YAML parsed file. For example:

    fs::blocking::RewriteFileContents(path_to_file, R"(some_key: ['a', 'b'])");
    const auto yaml_content = fmt::format("some#file: {}", path_to_file);
    auto node = formats::yaml::FromString(yaml_content);
 
    yaml_config::YamlConfig yaml(std::move(node), {}, yaml_config::YamlConfig::Mode::kEnvAndFileAllowed);
    EXPECT_EQ(yaml["some"]["some_key"][0].As<std::string>(), "a");

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

# yaml
some_element:
    some: $variable
    some#file: /some/path/to/the/file.yaml
    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 is the content of the file with name file.yaml; otherwise the value is 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"]["some"].As<int>() is the value of ENV_NAME environment variable if it exists; otherwise it is 5.

Note: #env, #file and #fallback also work for keys inside config_vars.

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

Examples: samples/grpc_middleware_service/src/middlewares/server/meta_filter.cpp, and samples/grpc_middleware_service/src/middlewares/server/meta_filter.hpp.

Definition at line 72 of file yaml_config.hpp.

Inheritance diagram for yaml_config::YamlConfig:

Classes
struct	DefaultConstructed

struct	IterTraits

Public Types
enum class	Mode { kSecure , kEnvAllowed , kEnvAndFileAllowed }

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.

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.

formats::yaml::Value	GetRawYamlWithoutConfigVars () const
	Get the plain Yaml without substitutions. It may contain raw references.

Member Typedef Documentation

◆ const_iterator

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

Definition at line 88 of file yaml_config.hpp.

◆ Exception

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

Definition at line 89 of file yaml_config.hpp.

◆ ParseException

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

Definition at line 90 of file yaml_config.hpp.

Member Enumeration Documentation

◆ Mode

enum class yaml_config::YamlConfig::Mode

strong

Enumerator
kEnvAllowed	< secure mode, without reading environment variables or files
kEnvAndFileAllowed	< allows reading of environment variables

Definition at line 81 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_middleware_service/src/middlewares/server/meta_filter.cpp, samples/postgres_auth/auth_bearer.cpp, and samples/ydb_service/components/topic_reader.cpp.

Definition at line 217 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 252 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 242 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.

◆ GetRawYamlWithoutConfigVars()

formats::yaml::Value yaml_config::YamlConfig::GetRawYamlWithoutConfigVars ( ) const

Get the plain Yaml without substitutions. It may contain raw references.

Deprecated: Either use the current YamlConfig as a formats value, or use .As<formats::json::Value>() to get the correct treatment for $vars, #fallback, #env and #file.

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

Friends And Related Symbol Documentation

◆ Parse

formats::yaml::Value Parse	(	const YamlConfig &	value,
		formats::parse::To< formats::yaml::Value >	)

friend

Flattens a YamlConfig, applying all of its special syntax.

Exceptions

yaml_config::YamlConfig::Exception if value.IsMissing()

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

userver/yaml_config/yaml_config.hpp

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

◆ GetRawYamlWithoutConfigVars()

◆ GetSize()

◆ HasMember()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

Friends And Related Symbol Documentation

◆ Parse