cpptoml

cpptoml supports extended TOML v0.5.0 date/time formats:

• local_date: Date only (e.g., 1980-08-02). Fields: year, month, day.
• local_time: Time only (e.g., 12:10:03.001). Fields: hour, minute, second, microsecond.
• local_datetime: Date and time without zone (e.g., 1980-08-02T12:10:03.001). Fields: all date and time fields.
• offset_datetime: Date, time, and timezone (e.g., 1980-08-02T12:10:03.001-07:00). Fields: all date/time fields plus hour_offset and minute_offset.

Use cpptoml::offset_datetime::from_zoned() and cpptoml::offset_datetime::from_utc() to convert struct tm objects to cpptoml::offset_datetime.

cpptoml is a header-only library. It requires a well-conforming C++11 compiler.

• OSX: clang++ with libc++ and libc++abi (standard with Xcode command line tools).
• Linux: g++ >= 4.8.x or clang++ with libc++ and libc++abi.

To compile the included examples using CMake:

mkdir build
cd build
cmake ../
make

There are two ways to access keys within nested tables:

1. Qualified Access (Idiomatic): Use get_qualified_as<T>(path) where the path is a dot-separated string (e.g., "table.inner.key").
2. Step-by-step Access: Use get_table(key) or get_table_qualified(path) to retrieve a sub-table, then call get_as<T>(key) on that table object.

// Method 1: Qualified access
auto key3 = config->get_qualified_as<std::string>("first-table.inner.key3");

// Method 2: Step-by-step
auto first = config->get_table("first-table");
auto inner = first->get_table("inner");
auto key3 = inner->get_as<std::string>("key3");

// Method 2b: Qualified table access
auto inner2 = config->get_table_qualified("first-table.inner");

To retrieve basic types (like int64_t, double, std::string), use the get_as<T>(key) method. This returns a cpptoml::option<T>.

• If the key exists and matches type T, the option evaluates to true.
• If the key is missing or the type is incorrect, the option evaluates to false.
• You can use .value_or(default_value) on the returned option to provide a fallback value.

// Get an integer with existence check
auto val = config->get_as<int64_t>("my-int");
if (val)
{
    // *val is the integer value
}

// Get a double with a default value
auto baz = config->get_as<double>("baz").value_or(0.5);

TOML arrays of tables (e.g., [[table-array]]) are treated as a distinct type. Use get_table_array(key) to retrieve them. This returns a cpptoml::option<std::vector<std::shared_ptr<cpptoml::table>>>.

auto tarr = config->get_table_array("table-array");
if (tarr) {
    for (const auto& table : *tarr) {
        auto key1 = table->get_as<std::string>("key1");
    }
}

Use get_array_of<T>(key) to retrieve an array. It returns a cpptoml::option<std::vector<T>>. The option will be empty if the key is missing, is not an array, or contains elements that cannot be cast to type T.

For nested arrays, you can retrieve an array of cpptoml::array objects and then query the elements within them.

// Simple array
auto vals = config->get_array_of<int64_t>("arr");
if (vals) {
    for (const auto& val : *vals) { /* use val */ }
}

// Nested arrays
auto nested = config->get_array_of<cpptoml::array>("mixed-arr");
auto ints = (*nested)[0]->get_array_of<int64_t>();
auto strings = (*nested)[1]->get_array_of<std::string>();

Use cpptoml::parse_file() to load a configuration file. It returns a shared pointer to a cpptoml::table. If parsing fails, it throws a cpptoml::parse_exception containing the line number and error description.

auto config = cpptoml::parse_file("config.toml");