llarp::ConfigDefinition

A ConfigDefinition holds an ordered set of OptionDefinitions defining the allowable values and their constraints (specified through calls to defineOption()). More...

#include <definition.hpp>

Public Functions

	Name
	ConfigDefinition(bool relay)
ConfigDefinition &	defineOption(OptionDefinition_ptr def) Specify the parameters and type of a configuration option.
template <typename T ,typename... Params> ConfigDefinition &	defineOption(Params &&... args) Convenience function which calls defineOption with a OptionDefinition of the specified type and with parameters passed through to OptionDefinition's constructor.
ConfigDefinition &	addConfigValue(std::string_view section, std::string_view name, std::string_view value) Specify a config value for the given section and name.
template <typename T > std::optional< T >	getConfigValue(std::string_view section, std::string_view name) Get a config value.
void	addUndeclaredHandler(const std::string & section, UndeclaredValueHandler handler) Add an "undeclared" handler for the given section.
void	removeUndeclaredHandler(const std::string & section) Removes an "undeclared" handler for the given section.
void	validateRequiredFields() Validate that all required fields are present.
void	acceptAllOptions() Accept all options.
void	process() validates and accept all parsed options
void	addSectionComments(const std::string & section, std::vector< std::string > comments) Add comments for a given section.
void	addOptionComments(const std::string & section, const std::string & name, std::vector< std::string > comments) Add comments for a given option.
std::string	generateINIConfig(bool useValues =false) Generate a config string from the current config definition, optionally using overridden values.

Detailed Description

struct llarp::ConfigDefinition;

A ConfigDefinition holds an ordered set of OptionDefinitions defining the allowable values and their constraints (specified through calls to defineOption()).

The layout and grouping of the config options are modelled after the INI file format; each option has a name and is grouped under a section. Duplicate option names are allowed only if they exist in a different section. The ConfigDefinition can be serialized in the INI file format using the generateINIConfig() function.

Configured values (e.g. those encountered when parsing a file) can be provided through calls to addConfigValue(). These take a std::string as a value, which is automatically parsed.

The ConfigDefinition can be used to print out a full config string (or file), including fields with defaults and optionally fields which have a specified value (values provided through calls to addConfigValue()).

Public Functions Documentation

function ConfigDefinition

inline explicit ConfigDefinition(
    bool relay
)

function defineOption

ConfigDefinition & defineOption(
    OptionDefinition_ptr def
)

Specify the parameters and type of a configuration option.

Parameters:

def should be a unique_ptr to a valid subclass of OptionDefinitionBase

Exceptions:

std::invalid_argument if the option already exists

Return: *this for chaining calls

The parameters are members of OptionDefinitionBase; the type is inferred from OptionDefinition's template parameter T.

This function should be called for every option that this Configuration supports, and should be done before any other interactions involving that option.

function defineOption

template <typename T ,
typename... Params>
inline ConfigDefinition & defineOption(
    Params &&... args
)

Convenience function which calls defineOption with a OptionDefinition of the specified type and with parameters passed through to OptionDefinition's constructor.

function addConfigValue

ConfigDefinition & addConfigValue(
    std::string_view section,
    std::string_view name,
    std::string_view value
)

Specify a config value for the given section and name.

Parameters:

section is the section this value resides in
name is the name of the value

Exceptions:

if the option doesn't exist or the provided string isn't parseable

Return: *this for chaining calls

The value should be a valid string representing the type used by the option (e.g. the type provided when defineOption() was called).

If the specified option doesn't exist, an exception will be thrown. Otherwise, the option's parseValue() will be invoked, and should throw an exception if the string can't be parsed.

function getConfigValue

template <typename T >
inline std::optional< T > getConfigValue(
    std::string_view section,
    std::string_view name
)

Get a config value.

Parameters:

section is the section this value resides in
name is the name of the value

Exceptions:

std::invalid_argument if there is no such config option or the wrong type T was

Return: an optional providing the configured value, the default, or empty

If the value hasn't been provided but a default has, the default will be returned. If no value and no default is provided, an empty optional will be returned.

The type T should exactly match that provided by the definition; it is not sufficient for one type to be a valid substitution for the other.

function addUndeclaredHandler

void addUndeclaredHandler(
    const std::string & section,
    UndeclaredValueHandler handler
)

Add an "undeclared" handler for the given section.

Parameters:

section is the section for which any undeclared values will invoke the provided handler
handler

Exceptions:

if there is already a handler for this section

This is a handler that will be called whenever a k:v pair is found that doesn't match a provided definition.

Any exception thrown by the handler will progagate back through the call to addConfigValue().

function removeUndeclaredHandler

void removeUndeclaredHandler(
    const std::string & section
)

Removes an "undeclared" handler for the given section.

Parameters:

section is the section which we want to remove the handler for

function validateRequiredFields

void validateRequiredFields()

Validate that all required fields are present.

Exceptions:

std::invalid_argument if configuration constraints are not met

function acceptAllOptions

void acceptAllOptions()

Accept all options.

Exceptions:

if any option's acceptor throws

This will call the acceptor (if present) on each option. Note that this should only be called if all required fields are present (that is, validateRequiredFields() has been or could be called without throwing).

function process

inline void process()

validates and accept all parsed options

function addSectionComments

void addSectionComments(
    const std::string & section,
    std::vector< std::string > comments
)

Add comments for a given section.

Parameters:

section
comment

Comments are replayed in-order during config file generation. A proper comment prefix will automatically be applied, and the entire comment will otherwise be used verbatim (no automatic line separation, etc.).

function addOptionComments

void addOptionComments(
    const std::string & section,
    const std::string & name,
    std::vector< std::string > comments
)

Add comments for a given option.

Parameters:

section
name
comment

Similar to addSectionComment, but applies to a specific [section]:name pair.

function generateINIConfig

std::string generateINIConfig(
    bool useValues =false
)

Generate a config string from the current config definition, optionally using overridden values.

Parameters:

useValues specifies whether we use specified values (e.g. those from calls to addConfigValue()) or only definitions

Return: a string containing the config in INI format

The generated config will preserve insertion order of both sections and their definitions.

Definitions which are required or have an overriden value (and useValues == true) will be written normally. Otherwise, they will be written commented-out in order to provide a complete documentation of the configuration file.

Updated on 2026-01-10 at 22:49:45 +0000