{"id":13495035,"url":"https://github.com/marzer/tomlplusplus","last_synced_at":"2025-05-14T02:07:42.625Z","repository":{"id":37506214,"uuid":"224503712","full_name":"marzer/tomlplusplus","owner":"marzer","description":"Header-only TOML config file parser and serializer for C++17.","archived":false,"fork":false,"pushed_at":"2025-05-07T08:01:24.000Z","size":21365,"stargazers_count":1728,"open_issues_count":17,"forks_count":169,"subscribers_count":31,"default_branch":"master","last_synced_at":"2025-05-07T08:44:37.686Z","etag":null,"topics":["c-plus-plus-17","c-plus-plus-20","configuration-files","cplusplus-17","cplusplus-20","cpp","cpp17","cpp20","header-only","json","no-dependencies","parser","serializer","single-file","toml","toml-parser","toml-parsing","tomlplusplus","unicode","utf-8"],"latest_commit_sha":null,"homepage":"https://marzer.github.io/tomlplusplus/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marzer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"marzer"}},"created_at":"2019-11-27T19:34:20.000Z","updated_at":"2025-05-07T07:59:24.000Z","dependencies_parsed_at":"2023-01-30T00:30:56.101Z","dependency_job_id":"e62b0f17-265f-46e4-a7a3-6046f6dda776","html_url":"https://github.com/marzer/tomlplusplus","commit_stats":{"total_commits":343,"total_committers":39,"mean_commits":8.794871794871796,"dds":"0.16326530612244894","last_synced_commit":"c4369ae1d8955cae20c4ab40b9813ef4b60e48be"},"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marzer%2Ftomlplusplus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marzer%2Ftomlplusplus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marzer%2Ftomlplusplus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marzer%2Ftomlplusplus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marzer","download_url":"https://codeload.github.com/marzer/tomlplusplus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254052887,"owners_count":22006717,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c-plus-plus-17","c-plus-plus-20","configuration-files","cplusplus-17","cplusplus-20","cpp","cpp17","cpp20","header-only","json","no-dependencies","parser","serializer","single-file","toml","toml-parser","toml-parsing","tomlplusplus","unicode","utf-8"],"created_at":"2024-07-31T19:01:30.576Z","updated_at":"2025-05-14T02:07:37.612Z","avatar_url":"https://github.com/marzer.png","language":"C++","readme":"[![banner](docs/images/banner.png)][homepage]\n[![Releases](https://img.shields.io/github/v/release/marzer/tomlplusplus?style=flat-square)](https://github.com/marzer/tomlplusplus/releases)\n[![C++17](docs/images/badge-C++17.svg)][cpp_compilers]\n[![TOML](docs/images/badge-TOML.svg)][v1.0.0]\n[![MIT license](docs/images/badge-license-MIT.svg)](./LICENSE)\n[![ci](https://github.com/marzer/tomlplusplus/actions/workflows/ci.yaml/badge.svg?branch=master)](https://github.com/marzer/tomlplusplus/actions/workflows/ci.yaml)\n[![Mentioned in Awesome C++](docs/images/badge-awesome.svg)](https://github.com/fffaraz/awesome-cpp)\n[![Sponsor](docs/images/badge-sponsor.svg)](https://github.com/sponsors/marzer)\n[![Gitter](docs/images/badge-gitter.svg)](https://gitter.im/marzer/tomlplusplus)\n====\n\n## toml++ homepage\n\n\u003cp align=\"center\"\u003e\n\t\u003cstrong\u003e✨\u0026#xFE0F; This README is fine, but the \u003ca href=\"https://marzer.github.io/tomlplusplus/\"\u003etoml++ homepage\u003c/a\u003e is better. ✨\u0026#xFE0F;\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\n## Library features\n\n-   Header-only (optional!)\n-   Module support\n-   Supports the latest [TOML] release ([v1.0.0]), plus optional support for some unreleased TOML features\n-   Passes all tests in the [toml-test](https://github.com/toml-lang/toml-test) suite\n-   Supports serializing to JSON and YAML\n-   Proper UTF-8 handling (incl. BOM)\n-   C++17 (plus some C++20 features where available, e.g. experimental support for [char8_t] strings)\n-   Doesn't require RTTI\n-   Works with or without exceptions\n-   Tested on Clang (8+), GCC (8+) and MSVC (VS2019)\n-   Tested on x64, x86 and ARM\n\n\u003cbr\u003e\n\n## Basic usage\n\n\u003e ℹ\u0026#xFE0F; _The following example favours brevity. If you'd prefer full API documentation and lots of specific code\n\u003e snippets instead, visit the project [homepage]_\n\nGiven a [TOML] file `configuration.toml` containing the following:\n\n```toml\n[library]\nname = \"toml++\"\nauthors = [\"Mark Gillard \u003cmark.gillard@outlook.com.au\u003e\"]\n\n[dependencies]\ncpp = 17\n```\n\nReading it in C++ is easy with toml++:\n\n```cpp\n#include \u003ctoml++/toml.hpp\u003e\n\nusing namespace std::literals;\n\nauto config = toml::parse_file( \"configuration.toml\" );\n\n// get key-value pairs\nstd::string_view library_name = config[\"library\"][\"name\"].value_or(\"\"sv);\nstd::string_view library_author = config[\"library\"][\"authors\"][0].value_or(\"\"sv);\nint64_t depends_on_cpp_version = config[\"dependencies\"][\"cpp\"].value_or(0);\n\n// modify the data\nconfig.insert_or_assign(\"alternatives\", toml::array{\n    \"cpptoml\",\n    \"toml11\",\n    \"Boost.TOML\"\n});\n\n// use a visitor to iterate over heterogenous data\nconfig.for_each([](auto\u0026 key, auto\u0026 value)\n{\n    std::cout \u003c\u003c value \u003c\u003c \"\\n\";\n    if constexpr (toml::is_string\u003cdecltype(value)\u003e)\n        do_something_with_string_values(value);\n});\n\n// you can also iterate more 'traditionally' using a ranged-for\nfor (auto\u0026\u0026 [k, v] : config)\n{\n    // ...\n}\n\n// re-serialize as TOML\nstd::cout \u003c\u003c config \u003c\u003c \"\\n\";\n\n// re-serialize as JSON\nstd::cout \u003c\u003c toml::json_formatter{ config } \u003c\u003c \"\\n\";\n\n// re-serialize as YAML\nstd::cout \u003c\u003c toml::yaml_formatter{ config } \u003c\u003c \"\\n\";\n\n```\n\nYou'll find some more code examples in the `examples` directory, and plenty more as part of the [API documentation].\n\n\u003cbr\u003e\n\n## Adding toml++ to your project\n\n`toml++` comes in two flavours: Single-header and Regular. The API is the same for both.\n\n### 🍦\u0026#xFE0F; Single-header flavour\n\n1. Drop [`toml.hpp`] wherever you like in your source tree\n2. There is no step two\n\n### 🍨\u0026#xFE0F; Regular flavour\n\n1. Clone the repository\n2. Add `tomlplusplus/include` to your include paths, or for optional module support add `tomlplusplus/modules` as well and enable `TOMLPLUSPLUS_BUILD_MODULES`\n3. `#include \u003ctoml++/toml.hpp\u003e` (or `import tomlplusplus;`)\n\n### Conan\n\nAdd `tomlplusplus/3.4.0` to your conanfile.\n\n### DDS\n\nAdd `tomlpp` to your `package.json5`, e.g.:\n\n```plaintext\ndepends: [\n    'tomlpp^3.4.0',\n]\n```\n\n\u003e ℹ\u0026#xFE0F; _[What is DDS?](https://dds.pizza/)_\n\n### Tipi.build\n\n`tomlplusplus` can be easily used in [tipi.build](https://tipi.build) projects by adding the following entry to your `.tipi/deps`:\n\n```json\n{\n\t\"marzer/tomlplusplus\": {}\n}\n```\n\n### Vcpkg\n\n```plaintext\nvcpkg install tomlplusplus\n```\n\n### Meson\n\nYou can install the wrap with:\n\n```plaintext\nmeson wrap install tomlplusplus\n```\n\nAfter that, you can use it like a regular dependency:\n\n```meson\ntomlplusplus_dep = dependency('tomlplusplus')\n```\n\nYou can also add it as a subproject directly.\n\n### CMake FetchContent\n\n```cmake\ninclude(FetchContent)\nFetchContent_Declare(\n    tomlplusplus\n    GIT_REPOSITORY https://github.com/marzer/tomlplusplus.git\n    GIT_TAG        v3.4.0\n)\nFetchContent_MakeAvailable(tomlplusplus)\n# Example add library: target_link_libraries(MyApp tomlplusplus::tomlplusplus)\n```\n\n\u003e ℹ\u0026#xFE0F; _[What is FetchContent?](https://cmake.org/cmake/help/latest/module/FetchContent.html)_\n\n### Git submodules\n\n```plaintext\ngit submodule add --depth 1 https://github.com/marzer/tomlplusplus.git tomlplusplus\n```\n\n### Other environments and package managers\n\nThe C++ tooling ecosystem is a fractal nightmare of unbridled chaos so naturally I'm not up-to-speed with all of the\navailable packaging and integration options. I'm always happy to see new ones supported, though! If there's some\nintegration you'd like to see and have the technical know-how to make it happen, feel free to\n[make a pull request](./CONTRIBUTING.md).\n\n### What about dependencies?\n\nIf you just want to consume `toml++` as a regular library then you don't have any dependencies to worry about.\nThere's a few test-related dependencies to be aware of if you're working on the library, though.\nSee [CONTRIBUTING] for information.\n\n\u003cbr\u003e\n\n## Configuration\n\nA number of configurable options are exposed in the form of preprocessor `#defines` Most likely you\nwon't need to mess with these at all, but if you do, set them before including toml++.\n\n| Option                            |      Type      | Description                                                                                               | Default               |\n| --------------------------------- | :------------: | --------------------------------------------------------------------------------------------------------- | --------------------- |\n| `TOML_ASSERT(expr)`               | function macro | Sets the assert function used by the library.                                                             | `assert()`            |\n| `TOML_CALLCONV`                   |     define     | Calling convention to apply to exported free/static functions.                                            | undefined             |\n| `TOML_CONFIG_HEADER`              | string literal | Includes the given header file before the rest of the library.                                            | undefined             |\n| `TOML_ENABLE_FORMATTERS`          |    boolean     | Enables the formatters. Set to `0` if you don't need them to improve compile times and binary size.       | `1`                   |\n| `TOML_ENABLE_FLOAT16`             |    boolean     | Enables support for the built-in `_Float16` type.                                                         | per compiler settings |\n| `TOML_ENABLE_PARSER`              |    boolean     | Enables the parser. Set to `0` if you don't need it to improve compile times and binary size.             | `1`                   |\n| `TOML_ENABLE_UNRELEASED_FEATURES` |    boolean     | Enables support for [unreleased TOML language features].                                                  | `0`                   |\n| `TOML_ENABLE_WINDOWS_COMPAT`      |    boolean     | Enables support for transparent conversion between wide and narrow strings.                               | `1` on Windows        |\n| `TOML_EXCEPTIONS`                 |    boolean     | Sets whether the library uses exceptions.                                                                 | per compiler settings |\n| `TOML_EXPORTED_CLASS`             |     define     | API export annotation to add to classes.                                                                  | undefined             |\n| `TOML_EXPORTED_MEMBER_FUNCTION`   |     define     | API export annotation to add to non-static class member functions.                                        | undefined             |\n| `TOML_EXPORTED_FREE_FUNCTION`     |     define     | API export annotation to add to free functions.                                                           | undefined             |\n| `TOML_EXPORTED_STATIC_FUNCTION`   |     define     | API export annotation to add to static functions.                                                         | undefined             |\n| `TOML_HEADER_ONLY`                |    boolean     | Disable this to explicitly control where toml++'s implementation is compiled (e.g. as part of a library). | `1`                   |\n| `TOML_IMPLEMENTATION`             |     define     | Define this to enable compilation of the library's implementation when `TOML_HEADER_ONLY` == `0`.         | undefined             |\n| `TOML_OPTIONAL_TYPE`              |   type name    | Overrides the `optional\u003cT\u003e` type used by the library if you need [something better than std::optional].   | undefined             |\n| `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             |\n| `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             |\n\n\u003e ℹ\u0026#xFE0F; _A number of these have ABI implications; the library uses inline namespaces to prevent you from accidentally\n\u003e linking incompatible combinations together._\n\n\u003cbr\u003e\n\n## TOML Language Support\n\nAt any given time the library aims to support whatever the [most recently-released version] of TOML is, with opt-in\nsupport for a number of unreleased features from the [TOML master] and some sane cherry-picks from the\n[TOML issues list] where the discussion strongly indicates inclusion in a near-future release.\n\nThe library advertises the most recent numbered language version it fully supports via the preprocessor\ndefines `TOML_LANG_MAJOR`, `TOML_LANG_MINOR` and `TOML_LANG_PATCH`.\n\n### **Unreleased language features:**\n\n-   [#516]: Allow newlines and trailing commas in inline tables\n-   [#562]: Allow hex floating-point values\n-   [#644]: Support `+` in key names\n-   [#671]: Local time of day format should support `09:30` as opposed to `09:30:00`\n-   [#687]: Relax bare key restrictions to allow additional unicode characters\n-   [#790]: Include an `\\e` escape code sequence (shorthand for `\\u001B`)\n-   [#796]: Include an `\\xHH` escape code sequence\n-   [#891]: Allow non-English scripts for unquoted keys\n\n\u003e ℹ\u0026#xFE0F; _`#define TOML_ENABLE_UNRELEASED_FEATURES 1` to enable these features (see [Configuration](#Configuration))._\n\n### 🔹\u0026#xFE0F; **TOML v1.0.0:**\n\nAll features supported, including:\n\n-   [#356]: Allow leading zeros in the exponent part of a float\n-   [#567]: Control characters are not permitted in comments\n-   [#571]: Allow raw tabs inside strings\n-   [#665]: Make arrays heterogeneous\n-   [#766]: Allow comments before commas in arrays\n\n### 🔹\u0026#xFE0F; **TOML v0.5.0:**\n\nAll features supported.\n\n\u003cbr\u003e\n\n## Contributing\n\nContributions are very welcome! Either by [reporting issues] or submitting pull requests.\nIf you wish to submit a pull request, please see [CONTRIBUTING] for all the details you need to get going.\n\n\u003cbr\u003e\n\n## License and Attribution\n\ntoml++ is licensed under the terms of the MIT license - see [LICENSE].\n\nUTF-8 decoding is performed using a state machine based on Bjoern Hoehrmann's '[Flexible and Economical UTF-8 Decoder]'.\n\n### With thanks to:\n\n-   **[@a-is](https://github.com/a-is)** - Fixed a bug\n-   **[@beastle9end](https://github.com/beastle9end)** - Made Windows.h include bypass\n-   **[@bjadamson](https://github.com/bjadamson)** - Reported some bugs and helped design a new feature\n-   **[@bobfang1992](https://github.com/bobfang1992)** - Reported a bug and created a [wrapper in python](https://github.com/bobfang1992/pytomlpp)\n-   **[@capuanob](https://github.com/capuanob)** - Integrated this project into OSSFuzz\n-   **[@GiulioRomualdi](https://github.com/GiulioRomualdi)** - Added cmake+meson support\n-   **[@jonestristand](https://github.com/jonestristand)** - Designed and implemented the `toml::path`s feature\n-   **[@kcsaul](https://github.com/kcsaul)** - Fixed a bug\n-   **[@levicki](https://github.com/levicki)** - Helped design some new features\n-   **[@mikomikotaishi](https://github.com/mikomikotaishi)** - Added support for C++20 modules\n-   **[@moorereason](https://github.com/moorereason)** - Reported a whole bunch of bugs\n-   **[@mosra](https://github.com/mosra)** - Created the awesome [m.css] used to generate the API docs\n-   **[@N-Dekker](https://github.com/N-Dekker)** - Added a workaround for the legacy lambda processor of MSVC 2019/2022, added `get_line`\n-   **[@ned14](https://github.com/ned14)** - Reported a bunch of bugs and helped design some new features\n-   **[@okureta](https://github.com/okureta)** - Reported a bug\n-   **[@prince-chrismc](https://github.com/prince-chrismc)** - Added toml++ to ConanCenter, and fixed some typos\n-   **[@rbrugo](https://github.com/rbrugo)** - Helped design a new feature\n-   **[@Reedbeta](https://github.com/Reedbeta)** - Fixed a bug and added additional Visual Studio debugger native visualizers\n-   **[@Ryan-rsm-McKenzie](https://github.com/Ryan-rsm-McKenzie)** - Add natvis file to cmake install script\n-   **[@Scrumplex](https://github.com/Scrumplex)** - Tweaked the build scripts\n-   **[@shdnx](https://github.com/shdnx)** - Fixed a bug on GCC 8.2.0 and some meson config issues\n-   **[@sneves](https://github.com/sneves)** - Helped fix a number of parser bugs\n-   **[@sobczyk](https://github.com/sobczyk)** - Reported some bugs\n-   **[@std-any-emplace](https://github.com/std-any-emplace)** - Reported some bugs\n-   **[@Tachi107](https://github.com/Tachi107)** - Made some tweaks to meson.build, added compile_library build option\n-   **[@traversaro](https://github.com/traversaro)** - Added vcpkg support and reported a bunch of bugs\n-   **[@tyler92](https://github.com/tyler92)** - Fixed stack overflow that occurred during fuzzing tests\n-   **[@whiterabbit963](https://github.com/whiterabbit963)** - Fixed a bug with value_or conversions\n-   **[@ximion](https://github.com/ximion)** - Added support for installation with meson\n\u003cbr\u003e\n\n## Contact\n\nFor bug reports and feature requests please consider using the [issues] system here on GitHub. For anything else\nthough you're welcome to reach out via other means. In order of likely response time:\n\n-   Gitter: [marzer/tomlplusplus](https://gitter.im/marzer/tomlplusplus) (\"Discord for repos\")\n-   Twitter: [marzer8789](https://twitter.com/marzer8789)\n-   Email: [mark.gillard@outlook.com.au](mailto:mark.gillard@outlook.com.au)\n-   Facebook: [marzer](https://www.facebook.com/marzer)\n-   LinkedIn: [marzer](https://www.linkedin.com/in/marzer/)\n\n[API documentation]: https://marzer.github.io/tomlplusplus/\n[homepage]: https://marzer.github.io/tomlplusplus/\n[unreleased TOML language features]: #unreleased-language-features\n[most recently-released version]: https://github.com/toml-lang/toml/releases\n[char8_t]: https://en.cppreference.com/w/cpp/keyword/char8_t\n[TOML]: https://toml.io/\n[TOML master]: https://github.com/toml-lang/toml/blob/master/README.md\n[TOML issues list]: https://github.com/toml-lang/toml/issues\n[v1.0.0]: https://toml.io/en/v1.0.0\n[CONTRIBUTING]: ./CONTRIBUTING.md\n[LICENSE]: ./LICENSE\n[Flexible and Economical UTF-8 Decoder]: http://bjoern.hoehrmann.de/utf-8/decoder/dfa/\n[cpp_compilers]: https://en.cppreference.com/w/cpp/compiler_support\n[reporting issues]: https://github.com/marzer/tomlplusplus/issues/new/choose\n[issues]: https://github.com/marzer/tomlplusplus/issues\n[#356]: https://github.com/toml-lang/toml/issues/356\n[#516]: https://github.com/toml-lang/toml/issues/516\n[#562]: https://github.com/toml-lang/toml/issues/562\n[#567]: https://github.com/toml-lang/toml/issues/567\n[#571]: https://github.com/toml-lang/toml/issues/571\n[#644]: https://github.com/toml-lang/toml/issues/644\n[#665]: https://github.com/toml-lang/toml/issues/665\n[#671]: https://github.com/toml-lang/toml/issues/671\n[#687]: https://github.com/toml-lang/toml/issues/687\n[#766]: https://github.com/toml-lang/toml/issues/766\n[#790]: https://github.com/toml-lang/toml/pull/790\n[#796]: https://github.com/toml-lang/toml/pull/796\n[#891]: https://github.com/toml-lang/toml/pull/891\n[something better than std::optional]: https://github.com/TartanLlama/optional\n[m.css]: https://mcss.mosra.cz/documentation/doxygen\n[`toml.hpp`]: https://raw.githubusercontent.com/marzer/tomlplusplus/master/toml.hpp\n","funding_links":["https://github.com/sponsors/marzer"],"categories":["Configuration","C++","Objects - Entity, Actor","Uncategorized","Data Formats","Libraries"],"sub_categories":["Saving/Loading Objects, Compositing Packets","Uncategorized","Parsing \u0026 Serialization"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarzer%2Ftomlplusplus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarzer%2Ftomlplusplus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarzer%2Ftomlplusplus/lists"}