toml++ homepage
✨️ This README is fine, but the
is better. ✨️
Library features
Header-only (optional!)
Module support
Supports the latest
release (
), plus optional support for some unreleased TOML features
Passes all tests in the
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
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
Basic usage
ℹ️ The following example favours brevity. If you'd prefer full API documentation and lots of specific code snippets instead, visit the project
Given a
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++/toml.hpp>usingnamespacestd::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"; ifconstexpr (toml::is_string<decltype(value)>) do_something_with_string_values(value); }); // you can also iterate more 'traditionally' using a ranged-forfor (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
.
Adding toml++ to your project
toml++ comes in two flavours: Single-header and Regular. The API is the same for both.
🍦️ Single-header flavour
Drop
wherever you like in your source tree
There is no step two
🍨️ Regular flavour
Clone the repository
Add tomlplusplus/include to your include paths, or for optional module support add tomlplusplus/modules as well and enable TOMLPLUSPLUS_BUILD_MODULES
#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', ] ℹ️
Tipi.build
tomlplusplus can be easily used in
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)ℹ️
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
.
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
for information.
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++.
OptionTypeDescriptionDefaultTOML_ASSERT(expr)function macroSets the assert function used by the library.assert()TOML_CALLCONVdefineCalling convention to apply to exported free/static functions.undefinedTOML_CONFIG_HEADERstring literalIncludes the given header file before the rest of the library.undefinedTOML_DISABLE_CONDITIONAL_NOEXCEPT_LAMBDAbooleanDisables the conditional noexcept's of internal lambda's. Needed for MSVC's "legacy lambda processor".0TOML_ENABLE_FORMATTERSbooleanEnables the formatters. Set to 0 if you don't need them to improve compile times and binary size.1TOML_ENABLE_FLOAT16booleanEnables support for the built-in _Float16 type.per compiler settingsTOML_ENABLE_PARSERbooleanEnables the parser. Set to 0 if you don't need it to improve compile times and binary size.1TOML_ENABLE_UNRELEASED_FEATURESbooleanEnables support for
unreleased TOML language features
.0TOML_ENABLE_WINDOWS_COMPATbooleanEnables support for transparent conversion between wide and narrow strings.1 on WindowsTOML_EXCEPTIONSbooleanSets whether the library uses exceptions.per compiler settingsTOML_EXPORTED_CLASSdefineAPI export annotation to add to classes.undefinedTOML_EXPORTED_MEMBER_FUNCTIONdefineAPI export annotation to add to non-static class member functions.undefinedTOML_EXPORTED_FREE_FUNCTIONdefineAPI export annotation to add to free functions.undefinedTOML_EXPORTED_STATIC_FUNCTIONdefineAPI export annotation to add to static functions.undefinedTOML_HEADER_ONLYbooleanDisable this to explicitly control where toml++'s implementation is compiled (e.g. as part of a library).1TOML_IMPLEMENTATIONdefineDefine this to enable compilation of the library's implementation when TOML_HEADER_ONLY == 0.undefinedTOML_OPTIONAL_TYPEtype nameOverrides the optional<T> type used by the library if you need
something better than std::optional
.undefinedTOML_SMALL_FLOAT_TYPEtype nameIf your codebase has a custom 'small float' type (e.g. half-precision), this tells toml++ about it.undefinedTOML_SMALL_INT_TYPEtype nameIf your codebase has a custom 'small integer' type (e.g. 24-bits), this tells toml++ about it.undefinedℹ️ A number of these have ABI implications; the library uses inline namespaces to prevent you from accidentally linking incompatible combinations together.
TOML Language Support
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
and some sane cherry-picks from the
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 language features:
: Allow newlines and trailing commas in inline tables
: Allow hex floating-point values
: Support + in key names
: Local time of day format should support 09:30 as opposed to 09:30:00
: Relax bare key restrictions to allow additional unicode characters
: Include an \e escape code sequence (shorthand for \u001B)
: Include an \xHH escape code sequence
: Allow non-English scripts for unquoted keys
ℹ️ #define TOML_ENABLE_UNRELEASED_FEATURES 1 to enable these features (see
).
🔹️ TOML v1.0.0:
All features supported, including:
: Allow leading zeros in the exponent part of a float
: Control characters are not permitted in comments
: Allow raw tabs inside strings
: Make arrays heterogeneous
: Allow comments before commas in arrays
🔹️ TOML v0.5.0:
All features supported.
Contributing
Contributions are very welcome! Either by
or submitting pull requests. If you wish to submit a pull request, please see
for all the details you need to get going.
License and Attribution
toml++ is licensed under the terms of the MIT license - see
.
UTF-8 decoding is performed using a state machine based on Bjoern Hoehrmann's '
Flexible and Economical UTF-8 Decoder
'.
With thanks to:
- Fixed a bug
- Made Windows.h include bypass
- Reported some bugs and helped design a new feature
- Reported a bug and created a
- Integrated this project into OSSFuzz
- Fixed stack overflow from deeply nested arrays/inline tables
- Fixed bug in CMake for modules support
- Added cmake+meson support
- Designed and implemented the toml::paths feature
- Fixed a bug
- Helped design some new features
- Added support for C++20 modules
- Reported a whole bunch of bugs
- Created the awesome
used to generate the API docs
- Added a workaround for the legacy lambda processor of MSVC 2019/2022, added get_line
- Reported a bunch of bugs and helped design some new features
- Reported a bug
- Added toml++ to ConanCenter, and fixed some typos
- Helped design a new feature
- Fixed a bug and added additional Visual Studio debugger native visualizers
- Add natvis file to cmake install script
- Tweaked the build scripts
- Fixed a bug on GCC 8.2.0 and some meson config issues
- Helped fix a number of parser bugs
- Reported some bugs
- Reported some bugs
- Made some tweaks to meson.build, added compile_library build option
- Added vcpkg support and reported a bunch of bugs
- Fixed stack overflow that occurred during fuzzing tests
- Fixed a bug with value_or conversions
- Added support for installation with meson
- Added a formatting flag
- Fixed a meson option
- Fixed reinterpret_cast usage
- Fixed a parser bug
Contact
For bug reports and feature requests please consider using the
system here on GitHub. For anything else though you're welcome to reach out via other means. In order of likely response time:
Gitter:
("Discord for repos")
Twitter:
Email:
Facebook:
LinkedIn: