toml++

TOML data is represented as a tree of toml::value, toml::array, and toml::table (all inheriting from toml::node). You can access elements using operator[] or at_path(), which return a toml::node_view.

Common operations include:

• Querying values: Use .value<T>() to get an std::optional<T> or .value_or(default) for a fallback.
• Accessing references: Use .ref<T>() for a direct reference (use with caution).
• Chaining: tbl["key1"]["key2"] allows deep querying.
• Arrays: Use .as_array() to get a pointer to the underlying toml::array for iteration (for_each) or modification (push_back).

#include <iostream>
#include <toml++/toml.hpp>
using namespace std::string_view_literals;

int main()
{
    static constexpr auto source = R"(
        str = "hello world"

        numbers = [ 1, 2, 3, "four", 5.0 ]
        vegetables = [ "tomato", "onion", "mushroom", "lettuce" ]
        minerals = [ "quartz", "iron", "copper", "diamond" ]

        [animals]
        cats = [ "tiger", "lion", "puma" ]
        birds = [ "macaw", "pigeon", "canary" ]
        fish = [ "salmon", "trout", "carp" ]
    )"sv;
    toml::table tbl = toml::parse(source);

    // different ways of directly querying data
    std::optional<std::string_view> str1 = tbl["str"].value<std::string_view>();
    std::optional<std::string>      str2 = tbl["str"].value<std::string>();
    std::string_view                str3 = tbl["str"].value_or(""sv);
    std::string&                    str4 = tbl["str"].ref<std::string>(); // ~~dangerous~~

    std::cout << *str1 << "\n";
    std::cout << *str2 << "\n";
    std::cout << str3 << "\n";
    std::cout << str4 << "\n";

    // get a toml::node_view of the element 'numbers' using operator[]
    auto numbers = tbl["numbers"];
    std::cout << "table has 'numbers': " << !!numbers << "\n";
    std::cout << "numbers is an: " << numbers.type() << "\n";
    std::cout << "numbers: " << numbers << "\n";

    // get the underlying array object to do some more advanced stuff
    if (toml::array* arr = numbers.as_array())
    {
        // visitation with for_each() helps deal with heterogeneous data
        arr->for_each([](auto&& el)
        {
            if constexpr (toml::is_number<decltype(el)>)
                (*el)++;
            else if constexpr (toml::is_string<decltype(el)>)
                el = "five"sv;
        });

        // arrays are very similar to std::vector
        arr->push_back(7);
        arr->emplace_back<toml::array>(8, 9);
        std::cout << "numbers: " << numbers << "\n";
    }

    // node-views can be chained to quickly query deeper
    std::cout << "cats: " << tbl["animals"]["cats"] << "\n";
    std::cout << "fish[1]: " << tbl["animals"]["fish"][1] << "\n";

    // can also be retrieved via absolute path
    std::cout << "cats: " << tbl.at_path("animals.cats") << "\n";
    std::cout << "fish[1]: " << tbl.at_path("animals.fish[1]") << "\n";

    // ...even if the element doesn't exist
    std::cout << "dinosaurs: " << tbl["animals"]["dinosaurs"] << "\n"; //no dinosaurs :(

    return 0;
}

toml++ can be integrated into your project using several methods:

Single-header (Easiest)

1. Download toml.hpp and place it in your source tree.

Regular flavour (Git/Manual)

1. Clone the repository.
2. Add tomlplusplus/include to your include paths.
3. (Optional) For module support, add tomlplusplus/modules and enable TOMLPLUSPLUS_BUILD_MODULES.

Package Managers

• Conan: Add tomlplusplus/3.4.0 to your conanfile.
• DDS: Add tomlpp^3.4.0 to your package.json5.
• Meson: Run meson wrap install tomlplusplus.
• Vcpkg: Run vcpkg install tomlplusplus.
• CMake: Use FetchContent.
• Git Submodules: git submodule add --depth 1 https://github.com/marzer/tomlplusplus.git tomlplusplus.

Python

Use the pytomlpp wrapper for high-performance TOML parsing in Python: pip install pytomlpp

// CMake FetchContent
include(FetchContent)
FetchContent_Declare(
    tomlplusplus
    GIT_REPOSITORY https://github.com/marzer/tomlplusplus.git
    GIT_TAG v3.4.0
)
FetchContent_MakeAvailable(tomlplusplus)

// Meson
meson wrap install tomlplusplus
tomlplusplus_dep = dependency('tomlplusplus')

// Git Submodule
git submodule add --depth 1 https://github.com/marzer/tomlplusplus.git tomlplusplus

// Python
pip install pytomlpp

Depending on your build system, use one of the following methods:

Conan Add tomlplusplus/3.4.0 to your conanfile.

DDS Add tomlpp to your package.json5:

depends: [
    'tomlpp^3.4.0',
]

Tipi.build Add the following to your .tipi/deps:

{
	"marzer/tomlplusplus": {}
}

Vcpkg

vcpkg install tomlplusplus

Meson

meson wrap install tomlplusplus

Then use in meson.build:

tomlplusplus_dep = dependency('tomlplusplus')

CMake (FetchContent)

include(FetchContent)
FetchContent_Declare(
    tomlplusplus
    GIT_REPOSITORY https://github.com/marzer/tomlplusplus.git
    GIT_TAG        v3.4.0
)
FetchContent_MakeAvailable(tomlplusplus)
# Link with: target_link_libraries(MyApp tomlplusplus::tomlplusplus)

Git Submodule

git submodule add --depth 1 https://github.com/marzer/tomlplusplus.git tomlplusplus

You can customize toml++ behavior using preprocessor #defines. These must be set before including the library. Note that some options have ABI implications; the library uses inline namespaces to prevent incompatible linking.

toml++ allows you to parse TOML files, manipulate data, and re-serialize it into TOML, JSON, or YAML formats.

Key operations include:

• Parsing: Use toml::parse_file to load a file into a configuration object.
• Accessing Data: Use the [] operator to navigate keys and .value_or(default) to safely retrieve values with a fallback.
• Modifying Data: Use insert_or_assign to add or update keys.
• Iteration: Use for_each with a visitor pattern or a ranged-for loop for (auto&& [k, v] : config) to traverse data.
• Serialization: Use std::cout << config for TOML, or use toml::json_formatter{ config } and toml::yaml_formatter{ config } for other formats.

#include <toml++/toml.hpp>

using namespace std::literals;

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

// get key-value pairs
std::string_view library_name = config["library"]["name"].value_or(""sv);
std::string_view library_author = config["library"]["authors"][0].value_or(""sv);
int64_t depends_on_cpp_version = config["dependencies"]["cpp"].value_or(0);

// modify the data
config.insert_or_assign("alternatives", toml::array{
    "cpptoml",
    "toml11",
    "Boost.TOML"
});

// use a visitor to iterate over heterogenous data
config.for_each([](auto& key, auto& value)
{
    std::cout << value << "\n";
    if constexpr (toml::is_string<decltype(value)>)
        do_something_with_string_values(value);
});

// you can also iterate more 'traditionally' using a ranged-for
for (auto&& [k, v] : config)
{
    // ...
}

// re-serialize as TOML
std::cout << config << "\n";

// re-serialize as JSON
std::cout << toml::json_formatter{ config } << "\n";

// re-serialize as YAML
std::cout << toml::yaml_formatter{ config } << "\n";