✨️ This README is fine, but the toml++ homepage is better. ✨️
- Header-only
- Supports the latest TOML release (v1.0.0), plus optional support for some unreleased TOML language features
- C++17 (plus some C++20 features where available, e.g. experimental support for char8_t strings)
- 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 (6+), GCC (7+) 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 <[email protected]>"]
[dependencies]
cpp = 17Reading it in C++ is easy with toml++:
#include <toml.hpp>
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"
});
// iterate & visit over the data
for (auto&& [k, v] : config)
{
v.visit([](auto& node) noexcept
{
std::cout << node << "\n";
if constexpr (toml::is_string<decltype(node)>)
do_something_with_string_values(node);
});
}
// re-serialize as TOML
std::cout << config << "\n";
// re-serialize as JSON
std::cout << toml::json_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.
- Drop
toml.hppwherever you like in your source tree - There is no step two
- Add
tomlplusplus/includeto your include paths #include <toml++/toml.h>
Add tomlplusplus/2.5.0 to your conanfile.
Add tomlpp to your package.json5, e.g.:
depends: [
'tomlpp^2.5.0',
]
ℹ️ What is DDS?
vcpkg install tomlplusplus
include(FetchContent)
FetchContent_Declare(
tomlplusplus
GIT_REPOSITORY https://github.com/marzer/tomlplusplus.git
GIT_TAG v2.5.0
)
FetchContent_MakeAvailable(tomlplusplus)
toml++ is a fairly new project and I'm not up-to-speed with all of the available packaging and integration options
in the C++ ecosystem. I'm also a cmake novice, for better or worse. If there's an integration option missing be
assured that I fully support it being added, and welcome pull requests!
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 | Default | Description |
|---|---|---|---|
TOML_HEADER_ONLY |
boolean | 1 |
Disable this to explicitly control where toml++'s implementation is compiled (e.g. as part of a library). |
TOML_API |
define | undefined | API annotation to add to public symbols (e.g. __declspec(dllexport) on Windows). |
TOML_ASSERT(expr) |
function macro | assert(expr)(or undefined) |
Sets the assert function used by the library. |
TOML_CONFIG_HEADER |
string literal | undefined | Includes the given header file before the rest of the library. |
TOML_EXCEPTIONS |
boolean | per your compiler's settings | Sets whether the library uses exceptions. |
TOML_IMPLEMENTATION |
define | undefined | Define this to enable compilation of the library's implementation. Meaningless if TOML_HEADER_ONLY is 1. |
TOML_LARGE_FILES |
boolean | 0 |
Uses 32-bit integers for line and column indices (instead of 16-bit). |
TOML_OPTIONAL_TYPE |
type name | undefined | Overrides the optional<T> type used by the library if you need something better than std::optional. |
TOML_PARSER |
boolean | 1 |
Disable this to prevent inclusion of the parser-related parts of the library if you don't need them. |
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_UNRELEASED_FEATURES |
boolean | 0 |
Enables support for unreleased TOML language features not yet part of a numbered version. |
TOML_WINDOWS_COMPAT |
boolean | 1 on Windows |
Enables support for transparent conversion between wide and narrow strings in some places when building for Windows. |
ℹ️ 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:30as opposed to09:30:00 - #687: Relax bare key restrictions to allow additional unicode characters
- #709: Include an \xHH escape code sequence
ℹ️
#define TOML_UNRELEASED_FEATURES 1to 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
- @levicki - Helped design some new features
- @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
- @shdnx - Fixed a bug on GCC 8.2.0 and some meson config issues
- @sobczyk - Reported some bugs
- @sneves - Helped fix a number of parser bugs
- @std-any-emplace - Reported some bugs
- @traversaro - Added vcpkg support and reported a bunch of bugs
- @ximion - Added support for installation with meson
- @whiterabbit963 - Fixed a bug with value_or conversions
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:
- Twitter: marzer8789
- Email: [email protected]
- Facebook: marzer
- LinkedIn: marzer