toml++ (tomlplusplus) ·

Header-only
C++17 (plus some C++20 features where available, e.g. experimental support for char8_t strings)
TOML v0.5.0, plus support for some unreleased TOML language features (these are optional)
Proper UTF-8 handling (incl. BOM)
Works with or without exceptions
Doesn't require RTTI
First-class support for serializing to JSON
Tested on Clang and GCC and MSVC (VS2019)

Example

Given a TOML file configuration.toml containing the following:

[library]
name = "toml++"
version = "0.1.0"
authors = ["Mark Gillard <mark@notarealwebsite.com>"]

[dependencies]
cpp = 17

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

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_version = config["library"]["version"].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"
});

// iterate & visit over the data
for (auto [k, v] : config)
{
    v.visit([](auto& node) noexcept
    {
        std::cout << node << std:endl;
        if constexpr (toml::is_string<decltype(node)>)
            do_something_with_string_values(node);
    });
}

// re-serialize as TOML
std::cout << config << std::endl;

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

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

Adding toml++ to your project

toml++ comes in two flavours: Regular and Single-header.

Regular mode

Add tomlplusplus/include to your include paths
#include <toml++/toml.h>

Single-header mode

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

The API is the same regardless of how you consume the library.

Configuration

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, butif you do, set them before including toml++.

Option	Type	Default	Description
`TOML_ASSERT(expr)`	function macro	`assert(expr)` (or undefined)	Sets the assert function used by the library.
`TOML_CHAR_8_STRINGS`	boolean	`0`	Uses C++20 char8_t-based strings as the toml string data type. *Experimental!*
`TOML_CONFIG_HEADER`	string literal	undefined	Includes the given header file before the rest of the library.
`TOML_LARGE_FILES`	boolean	`0`	Uses 32-bit integers for line and column indices (instead of 16-bit).
`TOML_SMALL_FLOAT_TYPE`	type name	undefined	If your codebase has an additional 'small' float type (e.g. half-precision), this tells toml++ about it.
`TOML_SMALL_INT_TYPE`	type name	undefined	If your codebase has an additional 'small' integer type (e.g. 24-bits), this tells toml++ about it.
`TOML_UNDEF_MACROS`	boolean	`1`	`#undefs` the library's internal macros at the end of the header.
`TOML_UNRELEASED_FEATURES`	boolean	`1`	Enables support for unreleased TOML language features not yet part of a numbered version.

TOML Language Support

At any given time toml++ aims to implement whatever the numbered version of TOML is, with the addition 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.

🔸Unreleased TOML features:

#356: Allow leading zeros in the exponent part of a float
#516: Allow newlines and trailing commas in inline tables
#562: Allow hex floatingpoint values
#567: Clarify that control characters are not permitted in comments
#571: Allow raw tabs inside strings
#644: Support + in key names
#665: Make arrays heterogeneous
#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

These can be disabled (and thus strict TOML v0.5.0 compliance enforced) by specifying TOML_UNRELEASED_FEATURES = 0 (see Configuration).

🔹TOML v0.5.0 and earlier:

All features supported.

Contributing

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.

License and Attribution

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', which is also subject to the terms of the MIT license - see LICENSE-utf8-decoder.

7.7 KiB Raw Blame History