✨️ This README is fine, but the toml++ homepage is better. ✨️

• Header-only (optional!)
• Supports the latest TOML release (v1.0.0), plus optional support for some unreleased TOML features
• Passes all tests in the toml-test suite
• Supports serializing to JSON and YAML
• Proper UTF-8 handling (incl. BOM)
• C++17 (plus some C++20 features where available, e.g. experimental support for char8_t strings)
• Doesn't require RTTI
• Works with or without exceptions
• Tested on Clang (8+), GCC (8+) and MSVC (VS2019)
• Tested on x64, x86 and ARM

ℹ️ The following example favours brevity. If you'd prefer full API documentation and lots of specific code snippets instead, visit the project homepage

Given a TOML file configuration.toml containing the following:

[library]
name = "toml++"
authors = ["Mark Gillard <mark.gillard@outlook.com.au>"]

[dependencies]
cpp = 17

Reading it in C++ is easy with toml++:

#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";

You'll find some more code examples in the examples directory, and plenty more as part of the API documentation.

toml++ comes in two flavours: Single-header and Regular. The API is the same for both.

1. Drop toml.hpp wherever you like in your source tree
2. There is no step two

1. Clone the repository
2. Add tomlplusplus/include to your include paths
3. #include <toml++/toml.hpp>

Add tomlplusplus/3.4.0 to your conanfile.

Add tomlpp to your package.json5, e.g.:

depends: [
    'tomlpp^3.4.0',
]

ℹ️ What is DDS?

tomlplusplus can be easily used in tipi.build projects by adding the following entry to your .tipi/deps:

{
	"marzer/tomlplusplus": {}
}

vcpkg install tomlplusplus

You can install the wrap with:

meson wrap install tomlplusplus

After that, you can use it like a regular dependency:

tomlplusplus_dep = dependency('tomlplusplus')

You can also add it as a subproject directly.

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

ℹ️ What is FetchContent?

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

The C++ tooling ecosystem is a fractal nightmare of unbridled chaos so naturally I'm not up-to-speed with all of the available packaging and integration options. I'm always happy to see new ones supported, though! If there's some integration you'd like to see and have the technical know-how to make it happen, feel free to make a pull request.

If you just want to consume toml++ as a regular library then you don't have any dependencies to worry about. There's a few test-related dependencies to be aware of if you're working on the library, though. See CONTRIBUTING for information.

A number of configurable options are exposed in the form of preprocessor #defines Most likely you won't need to mess with these at all, but if you do, set them before including toml++.

ℹ️ A number of these have ABI implications; the library uses inline namespaces to prevent you from accidentally linking incompatible combinations together.

At any given time the library aims to support whatever the most recently-released version of TOML is, with opt-in support for a number of unreleased features from the TOML master and some sane cherry-picks from the TOML issues list where the discussion strongly indicates inclusion in a near-future release.

The library advertises the most recent numbered language version it fully supports via the preprocessor defines TOML_LANG_MAJOR, TOML_LANG_MINOR and TOML_LANG_PATCH.

• #516: Allow newlines and trailing commas in inline tables
• #562: Allow hex floating-point values
• #644: Support + in key names
• #671: Local time of day format should support 09:30 as opposed to 09:30:00
• #687: Relax bare key restrictions to allow additional unicode characters
• #790: Include an \e escape code sequence (shorthand for \u001B)
• #796: Include an \xHH escape code sequence
• #891: Allow non-English scripts for unquoted keys

ℹ️ #define TOML_ENABLE_UNRELEASED_FEATURES 1 to enable these features (see Configuration).

All features supported, including:

• #356: Allow leading zeros in the exponent part of a float
• #567: Control characters are not permitted in comments
• #571: Allow raw tabs inside strings
• #665: Make arrays heterogeneous
• #766: Allow comments before commas in arrays

All features supported.

Contributions are very welcome! Either by reporting issues or submitting pull requests. If you wish to submit a pull request, please see CONTRIBUTING for all the details you need to get going.

toml++ is licensed under the terms of the MIT license - see LICENSE.

UTF-8 decoding is performed using a state machine based on Bjoern Hoehrmann's 'Flexible and Economical UTF-8 Decoder'.

• @beastle9end - Made Windows.h include bypass
• @bjadamson - Reported some bugs and helped design a new feature
• @bobfang1992 - Reported a bug and created a wrapper in python
• @GiulioRomualdi - Added cmake+meson support
• @jonestristand - Designed and implemented the toml::paths feature
• @kcsaul - Fixed a bug
• @levicki - Helped design some new features
• @moorereason - Reported a whole bunch of bugs
• @mosra - Created the awesome m.css used to generate the API docs
• @ned14 - Reported a bunch of bugs and helped design some new features
• @okureta - Reported a bug
• @prince-chrismc - Added toml++ to ConanCenter, and fixed some typos
• @rbrugo - Helped design a new feature
• @Reedbeta - Fixed a bug and added additional Visual Studio debugger native visualizers
• @Ryan-rsm-McKenzie - Add natvis file to cmake install script
• [@Scrumplex][https://github.com/Scrumplex) - Tweaked the build scripts
• @shdnx - Fixed a bug on GCC 8.2.0 and some meson config issues
• @sneves - Helped fix a number of parser bugs
• @sobczyk - Reported some bugs
• @std-any-emplace - Reported some bugs
• @Tachi107 - Made some tweaks to meson.build, added compile_library build option
• @traversaro - Added vcpkg support and reported a bunch of bugs
• @whiterabbit963 - Fixed a bug with value_or conversions
• @ximion - Added support for installation with meson
• @a-is - Fixed a bug
• @capuanob - Integrated this project into OSSFuzz
• [@tyler92] - Fixed stack overflow that occurred during fuzzing tests

For bug reports and feature requests please consider using the issues system here on GitHub. For anything else though you're welcome to reach out via other means. In order of likely response time:

• Gitter: marzer/tomlplusplus ("Discord for repos")
• Twitter: marzer8789
• Email: mark.gillard@outlook.com.au
• Facebook: marzer
• LinkedIn: marzer