Loading...
Searching...
No Matches
libconfig

# libconfig

libconfig is the unified configuration module for SERiF and related projects

This has been broken out of the main serif project to allow for more modularity

## Building

In order to build libconfig you need `meson>=1.5.0`. This can be installed with `pip`

pip install "meson>=1.5.0"

Then from the root libconfig directory it is as simple as

meson setup build --buildtype=release
meson compile -C build
meson test -C build

this will auto generate a pkg-config file for you so that linking other libraries to libconfig is easy.

## Usage

libconfig makes use of reflect-cpp to provide compile time reflection and serialization/deserialization of configuration structs. This allows for config options to be defined in code and strongly typed.

### Basic Usage

#include "fourdst/config/config.h"
#include <string>
#include <print>
#include <optional>
struct MyPhysicsOptions {
int gravity = 10;
float friction = 0.5f;
std::optional<float> dampening = 0.1f;
bool enable_wind = false;
};
struct MyControlOptions {
double time_step = 0.01;
double max_time = 100.0;
};
struct MySimulationConfig {
std::string name = "my_simulation";
MyPhysicsOptions physics;
MyControlOptions control;
};
int main() {
fourdst::config::Config<MySimulationConfig> cfg;
// You can save the default config to a file
cfg.save("default_config.toml");
// You can save the json schema for the config
// This allows editors like VS Code to provide autocompletion
fourdst::config::Config<MySimulationConfig>::save_schema("config.schema.json");
// You can load a config from a file
try {
cfg.load("my_config.toml");
// You can also pass an optional bool as a second argument to turn on verbose error
// reporting. This will display a tree of missing or invalid fields. Note that due to limitations
// in C++'s ability to detect default iniailized values vs initializer list values
// missing fields which you set an initializer list for are still considered missing.
// **ONLY fields marked with std::optional are exempt from this rule.**
} catch (const fourdst::config::exceptions::ConfigError& e) {
std::println("Error loading config: {}", e.what());
}
// You can access the config values
std::println("My Simulation Name: {}, My Simulation Gravity: {}", cfg->name, cfg->physics.gravity);
// libconfig intentioanlly discourages direct modification of config values. However, if you need
// to modify values after loading them you can use the mutate function. This takes a lambda
// which recives a mutable reference to the underlying config struct.
cfg.mutate([](MySimulationConfig& config) {
config->physics.enable_wind = true;
});
// Making these mutations will put the config into a "MODIFIED" state and will cache the unmodified values.
// You can reset the state and revert to the unmodified values with the reset function.
cfg.reset();
// The current state of the config can be checked with the get_state() function or the describe_state() function.
// get_state returns an enum value while describe_state returns a human readable string.
std::println("Config State: {}", cfg.describe_state());
fourdst::config::ConfigState state = cfg.get_state();
// Possible states are DEFAULT, LOADED_FROM_FILE, and MODIFIED
}
fourdst::config::Config
Wrapper class for managing strongly-typed configuration structures.
Definition base.h:117
fourdst::config::Config::describe_state
std::string describe_state() const
Returns a string description of the current configuration state.
Definition base.h:353
fourdst::config::Config::get_state
ConfigState get_state() const
Gets the current state of the configuration object.
Definition base.h:347
fourdst::config::Config::load
void load(const std::string_view path, const bool verbose=false)
Loads configuration from a TOML file.
Definition base.h:253
fourdst::config::Config::reset
void reset()
Definition base.h:375
fourdst::config::Config::save
void save(std::string_view path) const
Saves the current configuration to a TOML file.
Definition base.h:168
fourdst::config::Config::mutate
void mutate(MutatorFunc &&mutator)
Definition base.h:367
fourdst::config::Config::save_schema
static void save_schema(const std::string &path)
Generates and saves a JSON schema for the configuration structure.
Definition base.h:328
fourdst::config::exceptions::ConfigError
Base exception class for all configuration-related errors.
Definition exceptions.h:20
fourdst::config::exceptions::ConfigError::what
const char * what() const noexcept override
Returns the error message.
Definition exceptions.h:32
config.h
Main entry point for the fourdst::config library.
fourdst::config::ConfigState
ConfigState
Represents the current state of a Config object.
Definition base.h:62

### CLI Integration

libconfig integrates with CLI11 to automatically expose configuration fields as command-line arguments.

#include "CLI/CLI.hpp"
#include "fourdst/config/config.h"
int main(int argc, char** argv) {
fourdst::config::Config<MySimulationConfig> cfg;
CLI::App app("My Application");
// Automatically registers:
// --name
// --physics.gravity
// --physics.friction
// --physics.enable_wind
// ... and so on
fourdst::config::register_as_cli(cfg, app);
CLI11_PARSE(app, argc, argv);
// cfg is now populated with values from CLI arguments
return 0;
}
fourdst::config::register_as_cli
void register_as_cli(T &config, CliApp &app, const std::string &prefix="")
Registers configuration structure fields as CLI options.
Definition cli.h:114

## Example output TOML

[main]
name = "my_simulation"
[main.physics]
gravity = 10
friction = 0.5
enable_wind = false
[main.control]
time_step = 0.01
max_time = 100.0