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

---

# llarp::ConfigDefinition



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


`#include <definition.hpp>`

## Public Functions

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

## Detailed Description

```cpp
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](Classes/structllarp_1_1ConfigDefinition.md) can be serialized in the INI file format using the [generateINIConfig()](Classes/structllarp_1_1ConfigDefinition.md#function-generateiniconfig) function.

Configured values (e.g. those encountered when parsing a file) can be provided through calls to [addConfigValue()](Classes/structllarp_1_1ConfigDefinition.md#function-addconfigvalue). These take a std::string as a value, which is automatically parsed.

The [ConfigDefinition](Classes/structllarp_1_1ConfigDefinition.md) 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()](Classes/structllarp_1_1ConfigDefinition.md#function-addconfigvalue)). 

## Public Functions Documentation

### function ConfigDefinition

```cpp
inline explicit ConfigDefinition(
    bool relay
)
```


### function defineOption

```cpp
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](Classes/structllarp_1_1OptionDefinitionBase.md)


**Exceptions**: 

  * **std::invalid_argument** if the option already exists 


**Return**: `*this` for chaining calls 

The parameters are members of [OptionDefinitionBase](Classes/structllarp_1_1OptionDefinitionBase.md); the type is inferred from [OptionDefinition](Classes/structllarp_1_1OptionDefinition.md)'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

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

Convenience function which calls defineOption with a [OptionDefinition](Classes/structllarp_1_1OptionDefinition.md) of the specified type and with parameters passed through to [OptionDefinition](Classes/structllarp_1_1OptionDefinition.md)'s constructor. 

### function addConfigValue

```cpp
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()](Classes/structllarp_1_1ConfigDefinition.md#function-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

```cpp
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

```cpp
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()](Classes/structllarp_1_1ConfigDefinition.md#function-addconfigvalue).


### function removeUndeclaredHandler

```cpp
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

```cpp
void validateRequiredFields()
```

Validate that all required fields are present. 

**Exceptions**: 

  * **std::invalid_argument** if configuration constraints are not met 


### function acceptAllOptions

```cpp
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()](Classes/structllarp_1_1ConfigDefinition.md#function-validaterequiredfields) has been or could be called without throwing).


### function process

```cpp
inline void process()
```

validates and accept all parsed options 

### function addSectionComments

```cpp
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

```cpp
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

```cpp
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()](Classes/structllarp_1_1ConfigDefinition.md#function-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 2023-03-26 at 04:03:14 +0000