[][homepage] [][cpp_compilers] [][v1.0.0]

toml++ homepage

<p align="center"> <strong>✨&#xFE0F; This README is fine, but the <a href="https://marzer.github.io/tomlplusplus/">toml++ homepage</a> is better. ✨&#xFE0F;</strong> </p> <br>

Library features

• Header-only (optional!)
• Module support
• 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

<br>

Basic usage

ℹ️ 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].

<br>

Adding toml++ to your project

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

🍦️ Single-header flavour

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

🍨️ Regular flavour

1. Clone the repository
2. Add tomlplusplus/include to your include paths, or for optional module support add tomlplusplus/modules as well and enable TOMLPLUSPLUS_BUILD_MODULES
3. #include <toml++/toml.hpp> (or import tomlplusplus;)

Conan

Add tomlplusplus/3.4.0 to your conanfile.

DDS

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

depends: [
    'tomlpp^3.4.0',
]

ℹ️ What is DDS?

Tipi.build

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

{
	"marzer/tomlplusplus": {}
}

Vcpkg

vcpkg install tomlplusplus

Meson

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.

CMake FetchContent

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 submodules

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

Other environments and package managers

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.

What about dependencies?

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.

<br>

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

| Option | Type | Description | Default | | ------------------------------------------ | :------------: | --------------------------------------------------------------------------------------------------------- | --------------------- | | TOML_ASSERT(expr) | function macro | Sets the assert function used by the library. | assert() | | TOML_CALLCONV | define | Calling convention to apply to exported free/static functions. | undefined | | TOML_CONFIG_HEADER | string literal | Includes the given header file before the rest of the library. | undefined | | TOML_DISABLE_CONDITIONAL_NOEXCEPT_LAMBDA | boolean | Disables the conditional noexcept's of internal lambda's. Needed for MSVC's "legacy lambda processor". | 0 | | TOML_ENABLE_FORMATTERS | boolean | Enables the formatters. Set to 0 if you don't need them to improve compile times and binary size. | 1 | | TOML_ENABLE_FLOAT16 | boolean | Enables support for the built-in _Float16 type. | per compiler settings | | TOML_ENABLE_PARSER | boolean | Enables the parser. Set to 0 if you don't need it to improve compile times and binary size. | 1 | | TOML_ENABLE_UNRELEASED_FEATURES | boolean | Enables support for [unreleased TOML language features]. | 0 | | TOML_ENABLE_WINDOWS_COMPAT | boolean | Enables support for transparent conversion between wide and narrow strings. | 1 on Windows | | TOML_EXCEPTIONS | boolean | Sets whether the library uses exceptions. | per compiler settings | | TOML_EXPORTED_CLASS | define | API export annotation to add to classes. | undefined | | TOML_EXPORTED_MEMBER_FUNCTION | define | API export annotation to add to non-static class member functions. | undefined | | TOML_EXPORTED_FREE_FUNCTION | define | API export annotation to add to free functions. | undefined | | TOML_EXPORTED_STATIC_FUNCTION | define | API export annotation to add to static functions. | undefined | | TOML_HEADER_ONLY | boolean | Disable this to explicitly control where toml++'s implementation is compiled (e.g. as part of a library). | 1 | | TOML_IMPLEMENTATION | define | Define this to enable compilation of the library's implementation when TOML_HEADER_ONLY == 0. | undefined | | TOML_OPTIONAL_TYPE | type name | Overrides the optional<T> type used by the library if you need [something better than std::optional]. | undefined | | TOML_SMALL_FLOAT_TYPE | type name | If your codebase has a custom 'small float' type (e.g. half-precision), this tells toml++ about it. | undefined | | TOML_SMALL_INT_TYPE | type name | If your codebase has a custom 'small integer' type (e.g. 24-bits), this tells toml++ about it. | undefined |

ℹ️ _A number of these have ABI i