[hard fork] the existing library is written by some orange site/reddit lurking midwit incapable of adding custom types. on the other hand, they have no problem filling the repo with ~70klocs of third party shit, tests, fuzzers that in all reality arent going to catch any real bugs, and autogenerated project files.
Go to file
2020-04-03 16:51:04 +03:00
.circleci fixed parse_file for string literals (closes #12) 2020-03-03 23:28:24 +02:00
.github/ISSUE_TEMPLATE Update issue templates [skip ci] 2020-02-24 22:33:10 +02:00
docs support for upcoming TOML v1.0.0 release 2020-04-03 00:39:21 +03:00
examples added missing operator<< for parse_error 2020-02-25 23:11:40 +02:00
extern fixed parse_file for string literals (closes #12) 2020-03-03 23:28:24 +02:00
include/toml++ added operator[], begin(), end() to parse_result in noexcept-mode 2020-04-03 16:33:02 +03:00
python added operator[], begin(), end() to parse_result in noexcept-mode 2020-04-03 16:33:02 +03:00
tests added operator[], begin(), end() to parse_result in noexcept-mode 2020-04-03 16:33:02 +03:00
vs added operator[], begin(), end() to parse_result in noexcept-mode 2020-04-03 16:33:02 +03:00
.editorconfig minor documentation fixes 2020-03-27 11:46:10 +02:00
.gitattributes support for upcoming TOML v1.0.0 release 2020-04-03 00:39:21 +03:00
.gitignore moved date and time stuff to separate header 2020-01-11 23:15:24 +02:00
.gitmodules fixed parse_file for string literals (closes #12) 2020-03-03 23:28:24 +02:00
CODE_OF_CONDUCT.md Added code of conduct [skip ci] 2020-02-24 22:01:54 +02:00
CONTRIBUTING.md minor compilation speed and binary size improvements 2020-04-01 15:53:10 +03:00
LICENSE added support for \xHH escape sequences (unreleased) 2020-03-12 17:23:25 +02:00
meson_options.txt fixed compilation on older implementations without std::launder 2020-03-18 15:28:00 +02:00
meson.build meson: Permit installation of toml++ (#16) 2020-04-03 11:03:15 +03:00
README.md Added project homepage note to README [skip ci] 2020-04-03 16:51:04 +03:00
toml.hpp added operator[], begin(), end() to parse_result in noexcept-mode 2020-04-03 16:33:02 +03:00

banner
Releases C++17 C++20 TOML MIT license CircleCI Mentioned in Awesome C++

  • Header-only
  • TOML v1.0.0-rc.1, 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, GCC 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 homepage at marzer.github.io/tomlplusplus

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.hpp>
#include <fstream> //required for toml::parse_file()

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 << 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: 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. Add tomlplusplus/include to your include paths
  2. #include <toml++/toml.h>

"What about build system X, or package manager Y?"

Currently there's support for use as a meson submodule, which I think means it can be used with Conan. That's the extent of my knowledge in this area; clearly an area of opportunity! If you would like me to add support for a particular build system or package manager please let me know by making a feature request. Better still, if you have the skills and motivation to add support yourself, I'd welcome a pull request with a smile and open arms!


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 Default Description
TOML_ALL_INLINE 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_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_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_ALL_INLINE 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_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].

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 toml++ aims to implement whatever the most recently-released 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 features:

  • #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:30 as opposed to 09:30:00
  • #687: Relax bare key restrictions to allow additional unicode characters
  • #709: Include an \xHH escape code sequence

Unreleased features can be disabled (and thus strict TOML v1.0.0-rc.1 compliance enforced) by specifying TOML_UNRELEASED_FEATURES = 0 (see Configuration).

🟢 TOML v1.0.0-rc.1:

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

🟢 TOML v0.5.0:

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'.


Contact

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: