2020-01-04 14:21:38 +00:00
# toml++ (tomlplusplus)
2020-01-13 06:31:49 +00:00
![c++version ](https://img.shields.io/badge/c%2B%2B-17%2C%2020-informational )
[![tomlversion ](https://img.shields.io/badge/TOML-v0.5.0-informational )][v0.5.0]
2020-01-04 14:21:38 +00:00
[![CircleCI ](https://circleci.com/gh/marzer/tomlplusplus.svg?style=shield )](https://circleci.com/gh/marzer/tomlplusplus)
2020-01-13 06:31:49 +00:00
[![GitHub ](https://img.shields.io/github/license/marzer/tomlplusplus )](https://github.com/marzer/tomlplusplus/blob/master/LICENSE)
`toml++` is a header-only toml parser and serializer for C++17, C++20 and whatever comes after.
< br >
# Example
```cpp
/// example goes here.
```
You'll find some more code examples in
`examples` directory and plenty more as part of the [API documentation].
2020-01-04 14:21:38 +00:00
< br >
2020-01-13 06:31:49 +00:00
# Adding toml++ to your project
2020-01-04 14:21:38 +00:00
`toml++` comes in two flavours: Regular and Single-header.
### Regular mode
1. Add `tomlplusplus/include` to your include paths
2. `#include <toml++/toml.h>`
### Single-header mode
2020-01-13 06:31:49 +00:00
1. Drop `toml.hpp` wherever you like in your source tree
2020-01-04 14:21:38 +00:00
2. There is no step two
2020-01-13 06:31:49 +00:00
The API is the same regardless of how you consume the library.
2020-01-04 14:21:38 +00:00
2020-01-13 06:31:49 +00:00
### Configuration
2020-01-04 14:21:38 +00:00
A number of configurable options are exposed in the form of preprocessor macros. Most likely you
won't need to mess with these at all, but in the event you do, set your overrides prior to including
toml++.
2020-01-13 06:31:49 +00:00
| Option | Type | Default | Description |
|----------------------------|:--------------:|-----------------------------------|----------------------------------------------------------------------------------------------------------|
| `TOML_ASSERT(expr)` | function macro | `assert(expr)` < br > (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. |
| `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_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]. |
2020-01-04 14:21:38 +00:00
< br >
# 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_REVISION` .
2020-01-13 06:31:49 +00:00
### **🔸Unreleased TOML features:**
2020-01-04 14:21:38 +00:00
- [#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
- [#622]: Add short escaping alias `\s` for space (`\u0020`)
- [#644]: Support `+` in key names
- [#665]: Make arrays heterogeneous
- [#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
_These can be disabled (and thus strict [TOML v0.5.0] compliance enforced) by specifying
`TOML_UNRELEASED_FEATURES = 0` (see [Configuration ](#Configuration ))._
2020-01-13 06:31:49 +00:00
### **🔹TOML v0.5.0 and earlier:**
2020-01-04 14:21:38 +00:00
- All features as of `<< release date >>` .
< br >
# Contributing
Contributions are welcome, either by [reporting issues ](https://github.com/marzer/tomlplusplus/issues )
or submitting pull requests. If you wish to submit a PR, please be aware that:
- The single-header file `toml.hpp` is generated by a script; make your changes in the files in
`include` , **not** in `toml.hpp` .
2020-01-13 06:31:49 +00:00
- Your changes should compile warning-free on at least one of gcc 8.3.0, clang 8.0, and MSVC 19.2X
(Visual Studio 2019). All three is a bonus.
2020-01-04 14:21:38 +00:00
- You should regenerate the single-header file as part of your PR (a CI check will fail if you don't).
### Regenerating toml.hpp
1. Make your changes as necessary
2. If you've added a new header file that isn't going to be transitively included by one of the
others, add an include directive to `include/toml++/toml.h`
3. Run `python/generate_single_header.py`
### Building and testing
2020-01-13 06:31:49 +00:00
Testing is done using [Catch2], included in the respository as a submodule under `extern/Catch2` .
2020-01-04 14:21:38 +00:00
The first time you want to begin testing you'll need to ensure submodules have been fetched:
```bash
2020-01-13 06:31:49 +00:00
git submodule update --init --recursive extern/Catch2
2020-01-04 14:21:38 +00:00
```
#### Windows
Install [Visual Studio 2019] and [Test Adapter for Catch2], then open `vs/toml++.sln` and build the
projects in the `tests` solution folder. Visual Studio's Test Explorer should pick these up and
allow you to run the tests directly.
If test discovery fails, you can usually fix it by clicking enabling
`Auto Detect runsettings Files` (settings gear icon > `Configure Run Settings` ).
#### Linux
Install [meson] and [ninja] if necessary, then test with both gcc and clang:
```bash
CXX=g++ meson build-gcc
CXX=clang++ meson build-clang
2020-01-13 06:31:49 +00:00
cd build-gcc & & ninja & & ninja test
cd ../build-clang & & ninja & & ninja test
2020-01-04 14:21:38 +00:00
```
< br >
# 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]',
2020-01-13 06:31:49 +00:00
which is itself subject to the terms of (what appears to be) the MIT license. The license text is included in the
2020-01-04 14:21:38 +00:00
[relevant part ](https://github.com/marzer/tomlplusplus/blob/master/include/toml%2B%2B/toml_utf8.h )
of the toml++ source.
2020-01-13 06:31:49 +00:00
[API documentation]: https://marzer.github.io/tomlplusplus/namespacetoml.html
2020-01-04 14:21:38 +00:00
[unreleased TOML language features]: https://github.com/marzer/tomlplusplus#unreleased-features
[numbered version]: https://github.com/toml-lang/toml/releases
[char8_t]: https://en.cppreference.com/w/cpp/keyword/char8_t
[TOML master]: https://github.com/toml-lang/toml/blob/master/README.md
[TOML issues list]: https://github.com/toml-lang/toml/issues
[TOML v0.5.0]: https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.5.0.md
2020-01-13 06:31:49 +00:00
[v0.5.0]: https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.5.0.md
2020-01-04 14:21:38 +00:00
[LICENSE]: https://github.com/marzer/tomlplusplus/blob/master/LICENSE
[Flexible and Economical UTF-8 Decoder]: http://bjoern.hoehrmann.de/utf-8/decoder/dfa/
[meson]: https://mesonbuild.com/Getting-meson.html
[ninja]: https://github.com/ninja-build/ninja/wiki/Pre-built-Ninja-packages
2020-01-13 06:31:49 +00:00
[Catch2]: https://github.com/catchorg/Catch2
2020-01-04 14:21:38 +00:00
[Test Adapter for Catch2]: https://marketplace.visualstudio.com/items?itemName=JohnnyHendriks.ext01
[Visual Studio 2019]: https://visualstudio.microsoft.com/vs/
[#356]: https://github.com/toml-lang/toml/issues/356
[#516]: https://github.com/toml-lang/toml/issues/516
[#562]: https://github.com/toml-lang/toml/issues/562
[#567]: https://github.com/toml-lang/toml/issues/567
[#571]: https://github.com/toml-lang/toml/issues/571
[#622]: https://github.com/toml-lang/toml/issues/622
[#644]: https://github.com/toml-lang/toml/issues/644
[#665]: https://github.com/toml-lang/toml/issues/665
[#671]: https://github.com/toml-lang/toml/issues/671
[#687]: https://github.com/toml-lang/toml/issues/687