9ed295f21c
also: - documentation improvements - minor test restructuring |
||
---|---|---|
.circleci | ||
.github/ISSUE_TEMPLATE | ||
docs | ||
examples | ||
extern | ||
include/toml++ | ||
python | ||
tests | ||
vs | ||
.editorconfig | ||
.gitattributes | ||
.gitignore | ||
.gitmodules | ||
CODE_OF_CONDUCT.md | ||
CONTRIBUTING.md | ||
LICENSE | ||
LICENSE-utf8-decoder | ||
meson.build | ||
README.md | ||
toml.hpp |
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 to09: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.