AuroraMiddleware/tomlplusplus
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: fix some Markdown issues (#174)

Browse Source 
This small patch fixes some minor Markdown issues in the README and
CONTRIBUTING files:

- Add a blank line before and after block elements like lists and code
  blocks. This specified in the [original Markdown syntax] document,
  and can also create some issues with some parsers (see [MD32]).
- Add a blank line around headings, for the same reasons as above.
- Only use one top-level (H1) heading per document.
- Always specify a language in fenced code blocks, so that plugins like
  highlight.js can correctly highlight them
- Remove unused links from the bottom of README.md.

[original Markdown syntax]: https://daringfireball.net/projects/markdown/syntax
[MD32]: https://github.com/DavidAnson/markdownlint/blob/v0.26.2/doc/Rules.md#md032
This commit is contained in:
Andrea Pappacoda 2022-09-24 17:49:34 +02:00 committed by GitHub
parent fb8ce80350
commit 8aa5c8b2a4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 174 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

151
CHANGELOG.md
View File

@ -4,12 +4,17 @@
template:
## vX.X.X
[Released](https://github.com/marzer/tomlplusplus/releases/tag/vX.X.X) YYYY-MM-DD
#### Fixes:
#### Additions:
#### Changes:
#### Removals:
#### Build system:
<br><br>
@ -19,40 +24,47 @@ template:
## Unreleased
#### Fixes:
- fixed null pointer dereference in parser when exceptions are disabled (#169) (@ncaklovic)
<br><br>
## v3.2.0
[Released](https://github.com/marzer/tomlplusplus/releases/tag/v3.2.0) 2022-08-29
#### Fixes:
- fixed `[dotted.table]` source columns sometimes being off by one (#152) (@vaartis)
- fixed spurious `Wnull-dereference` warning on GCC (#164) (@zaporozhets)
- fixed `print_to_stream` ambiguity for `size_t` (#167) (@acronce)
#### Additions:
- added value type deduction to `emplace()` methods
- added `toml::path` utility type (#153, #156, #168) (@jonestristand, @kcsaul)
- added config option `TOML_CALLCONV`
- added missing relational operators for `source_position`
#### Changes:
- relaxed cvref requirements of `is_homogeneous()`, `emplace()`, `emplace_back()`, `emplace_hint()`
- relaxed mantissa and digits10 requirements of extended float support
<br><br>
## v3.1.0
[Released](https://github.com/marzer/tomlplusplus/releases/tag/v3.1.0) 2022-04-22
#### Fixes:
- fixed potential segfault when calling `at_path()` with an empty string
- fixed UB in internal unicode machinery (#144) (@kchalmer)
- fixed a number of spurious warnings with Clang 10 (#145, #146) (@chronoxor)
#### Additions:
- added `toml::array::for_each()`
- added `toml::table::for_each()`
- added config options `TOML_EXPORTED_CLASS`, `TOML_EXPORTED_MEMBER_FUNCTION`, `TOML_EXPORTED_STATIC_FUNCTION` &amp; `TOML_EXPORTED_FREE_FUNCTION`
@ -60,19 +72,20 @@ template:
- added support for more unicode in bare keys when using `TOML_ENABLE_UNRELEASED_FEATURES` ([toml/891](https://github.com/toml-lang/toml/pull/891))
#### Removals/Deprecations:
- deprecated old `TOML_API` option in favour new `TOML_EXPORTED_X` options
(it will continue to work as it did before if none of the new function export options are defined)
#### Build system:
- meson: added `compile_library` option (@Tachi107)
- meson: added `ubsan_tests` and `ubsan_examples` options
- meson: use system dependencies where available when building tests (@Tachi107)
<br><br>
## v3.0.1
[Released](https://github.com/marzer/tomlplusplus/releases/tag/v3.0.1) 2022-01-13
This is a single-bugfix release to fix an ODR issue for people using header-only mode in multiple
@ -80,20 +93,20 @@ translation units. If you aren't seeing linker errors because of `toml::array::i
this release holds nothing of value over v3.0.0.
#### Fixes:
- fixed erroneous use of `TOML_API` causing ODR issue (#136) (@Azarael)
- fixed erroneous use of `TOML_API` causing ODR issue (#136) (@Azarael)
<br><br>
## v3.0.0
[Released](https://github.com/marzer/tomlplusplus/releases/tag/v3.0.0) 2022-01-11
[Released](https://github.com/marzer/tomlplusplus/releases/tag/v3.0.0) 2022-01-11
This release will be a major version bump, so it's ABI breaks all around.
Any changes that are likely to cause migration issues (API changes, build system breakage, etc.) are indicated with ⚠&#xFE0F;.
#### Fixes:
- ⚠&#xFE0F; fixed `toml::table` init-list constructor requiring double-brackets
- ⚠&#xFE0F; fixed `TOML_API` + extern templates causing linker errors in some circumstances
- ⚠&#xFE0F; fixed incorrect `noexcept` specifications on many functions
@ -111,6 +124,7 @@ Any changes that are likely to cause migration issues (API changes, build system
- fixed strong exception guarantee edge-cases in `toml::table` and `toml::array`
#### Additions:
- added value flags to array + table insert methods (#44) (@levicki)
- added support for Unicode 14.0
- added support for ref categories and cv-qualifiers in `toml::node::ref()`
@ -145,6 +159,7 @@ Any changes that are likely to cause migration issues (API changes, build system
- added `operator->` to `toml::value` for class types
#### Changes:
- ⚠&#xFE0F; `toml::format_flags` is now backed by `uint64_t` (was previously `uint8_t`)
- ⚠&#xFE0F; `toml::source_index` is now an alias for `uint32_t` unconditionally (was previously dependent on `TOML_LARGE_FILES`)
- ⚠&#xFE0F; `toml::table` now uses `toml::key` as the key type (was previously `std::string`)
@ -163,50 +178,54 @@ Any changes that are likely to cause migration issues (API changes, build system
- updated conformance tests
#### Removals:
- ⚠&#xFE0F; removed `toml::format_flags::allow_value_format_flags`
- ⚠&#xFE0F; removed `TOML_LARGE_FILES` (it is now default - explicitly setting `TOML_LARGE_FILES` to `0` will invoke an `#error`)
- ⚠&#xFE0F; removed unnecessary template machinery (esp. where ostreams were involved)
- removed unnecessary uses of `final`
#### Build system:
- ⚠&#xFE0F; increased minimum required meson version to `0.54.0`
- disabled 'install' path when being used as a meson subproject (#114) (@Tachi107)
- fixed builds failing with meson 0.6.0 (#117) (@Tachi107)
- general meson improvements and fixes (#115) (@Tachi107)
- used `override_dependency` where supported (#116) (@Tachi107)
<br><br>
## v2.5.0
[Released](https://github.com/marzer/tomlplusplus/releases/tag/v2.5.0) 2021-07-11
#### Fixes:
- fixed linkage error with windows compat mode
- fixed `TOML_CONSTEVAL` broken in MSVC (again)
- fixed minor documentation bugs
- fixed cmake project version being incorrect (#110) (@GiulioRomualdi)
#### Additions:
- added support for lowercase 't' and 'z' in datetimes (per spec)
- added natvis file to cmake install (#106) (@Ryan-rsm-McKenzie)
- added VS cpp.hint file to cmake install
- added metafunctions `is_container`, `is_chronological`, `is_value`, `is_node`, `inserted_type_of`
#### Changes:
- improved debug code size by removing unnecessary std::forwards and std::moves
- modernized the CMake build files (#102, #103, #105) (@friendlyanon)
- updated conformance tests
<br><br>
## v2.4.0
[Released](https://github.com/marzer/tomlplusplus/releases/tag/v2.4.0) 2021-05-19
#### Fixes:
- fixed `node::value()` not retrieving inf and nan correctly
- fixed dotted kvps being unable to add subtables (#61) (@Validark)
- fixed linker error on linux ICC (#83) (@blackwer)
@ -224,20 +243,22 @@ Any changes that are likely to cause migration issues (API changes, build system
- fixed many small documentation issues
#### Additions:
- added proper cmake support (#85) (@ClausKlein)
- added cmake FetchContent information to documentation (#101) (@proydakov)
#### Removals:
- removed explicit `#include <fstream>` requirement for `parse_file()`
- removed explicit `#include <fstream>` requirement for `parse_file()`
<br><br>
## v2.3.0
[Released](https://github.com/marzer/tomlplusplus/releases/tag/v2.3.0) 2020-12-29
#### Fixes:
- fixed compiler errors caused by `<charconv>` with Apple-flavoured clang
- fixed array and table iterators missing `iterator_category` (#77) (@HazardyKnusperkeks)
- fixed `Wuseless-cast` warnings on GCC 10 (#75) (@HazardyKnusperkeks)
@ -249,14 +270,14 @@ Any changes that are likely to cause migration issues (API changes, build system
- fixed array and table iterators not converting between const and non-const versions of themselves (#67) (@std-any-emplace)
- fixed some parser crashes when given pathologically-malformed UTF-8 (#65) (@sneves)
<br><br>
## v2.2.0
[Released](https://github.com/marzer/tomlplusplus/releases/tag/v2.2.0) 2020-08-09
#### Fixes:
- fixed some issues building with VS2017 (#55) (@sobczyk)
- fixed `_Float16` erroneously detected as supported on g++ (#57) (@sobczyk)
- fixed `<Windows.h>` causing compilation failure on mingw (#63) (@rezahousseini)
@ -265,29 +286,32 @@ Any changes that are likely to cause migration issues (API changes, build system
- fixed ambiguous `operator==` error on MSVC (#56) (@HellsingDarge)
#### Additions:
- added additional node_view constructors
- added ability to specify serialization format of integer values
- added integer value serialization format round trip (e.g. hex in, hex out)
#### Changes:
- updated conformance tests
- TOML version bump to v1.0.0-rc.3
- refactors and cleanups based on feedback given [here](https://medium.com/@julienjorge/code-review-of-toml-f816a6071120)
#### Build system:
- renamed build options to `snake_case`
- tests, examples and cmake config now explicitly disabled when used as a subproject
- removed small_binaries (it's now implicit when building as release)
- bumped minimum meson version to 0.53
<br><br>
## v2.1.0
[Released](https://github.com/marzer/tomlplusplus/releases/tag/v2.1.0) 2020-07-11
#### Fixes:
- fixed inconsistent emission of leading/trailing newlines when writing a table to an ostream (#48) (@levicki)
- fixed `Wcast-align` warning spam on ARM
- fixed `array::insert` not working correctly in some cases
@ -297,6 +321,7 @@ Any changes that are likely to cause migration issues (API changes, build system
- fixed some minor documentation issues
#### Additions:
- added support for `__fp16`, `_Float16`, `__float128`, `__int128_t` and `__uint128_t`
- added copy construction/assignment for arrays, tables and values
- added insert, emplace, push_back etc. compatibility with node_views
@ -307,20 +332,21 @@ Any changes that are likely to cause migration issues (API changes, build system
- added implicit conversion operator from `node` to `node_view` (#52) (@Reedbeta)
#### Changes:
- renamed `TOML_ALL_INLINE` to `TOML_HEADER_ONLY` (the old name will still work, but is no longer documented)
- general cleanup
<br><br>
## v2.0.0
[Released](https://github.com/marzer/tomlplusplus/releases/tag/v2.0.0) 2020-07-20
This release contains a fairly significant number of 'quality of life' improvements, yay! But also necessitates an ABI
break (hence the version number bump). Changes that might block a migration are annotated with ⚠&#xFE0F;.
#### Fixes:
- fixed infinity and NaN-related code breaking when using `-ffast-math` and friends
- fixed narrowing conversion warnings when constructing int values from unsigned
- fixed Visual Studio debugger native visualizations for `date`, `time`, `time_offset`, `date_time`
@ -328,6 +354,7 @@ break (hence the version number bump). Changes that might block a migration are
- fixed internal macro `assert_or_assume` leaking out of `toml_parser.hpp`
#### Additions:
- added additional types allowed in `node::value()` and `node::value_or()` ([see `value()` dox for examples](https://marzer.github.io/tomlplusplus/classtoml_1_1node.html#ab144c1ae90338b6b03f6af0574c87993))
- added additional types allowed in `node_view::value()` and `node_view::value_or()`
- added `node::value_exact()` and `node_view::value_exact()`
@ -347,23 +374,25 @@ break (hence the version number bump). Changes that might block a migration are
- added explicit instantiations of more template types when `!TOML_ALL_INLINE`
#### Changes:
- ⚠&#xFE0F; deprecated `parse_result::get()` in favour of `parse_result::table()`
- ⚠&#xFE0F; deprecated `node_view::get()` in favour of `node_view::node()`
- ⚠&#xFE0F; simplified internal ABI namespaces
- improved the quality of many static_assert error messages
#### Removals:
- ⚠&#xFE0F; renamed `date_time::time_offset` to just 'offset'
- ⚠&#xFE0F; removed `TOML_CHAR_8_STRINGS` since it no longer makes sense
<br><br>
## v1.3.3
[Released](https://github.com/marzer/tomlplusplus/releases/tag/v1.3.3) 2020-06-29
#### Fixes:
- fixed some minor TOML spec conformance bugs
- fixed BOM check causing EOF on very short iostream inputs
- fixed `std::numeric_limits::max()` getting broken by macros in some environments
@ -371,61 +400,66 @@ break (hence the version number bump). Changes that might block a migration are
- fixed a few minor documentation issues
#### Additions:
- added rvalue overload of `array::flatten`
- added conformance tests from `BurntSushi/toml-test` and `iarna/toml-spec-tests`
- added `toml::inserter` as a workaround for nested construction of single-element `toml::arrays` performing move-construction instead
- added license boilerplate to test files
#### Changes:
- refactored the parser to reduce binary size
- refactored the parser to reduce binary size
<br><br>
## v1.3.2
[Released](https://github.com/marzer/tomlplusplus/releases/tag/v1.3.2) 2020-06-19
#### Fixes:
- fixed single-digit negative integers parsing as positive
- fixed parse failure when parsing an empty file
- fixed multi-line strings being allowed in keys
- fixed overflow for very long binary integer literals
#### Changes:
- improved the performance of toml::parse_file
- improved the performance of printing to streams for deepy-nested TOML data
<br><br>
## v1.3.0
[Released](https://github.com/marzer/tomlplusplus/releases/tag/v1.3.0) 2020-06-02
#### Fixes:
- fixed `formatter::print_inline()` causing compilation failures in DLL builds
- fixed BOMs occasionally causing overflow/crash in char8 mode
- fixed some spurious warnings in GCC 10
- fixed clang static analyzer warning in BOM handling code
#### Additions:
- added `table_iterator::operator ->`
- added `array::resize()` and `array::truncate()`
- added `array::capacity()`, `array::shrink_to_fit()`, `array::max_size()`
- added non-const -> const conversion for table and array iterators
#### Changes:
- renamed table iterator proxy pair members to `first` and `second` to match STL
- renamed table iterator proxy pair members to `first` and `second` to match STL
<br><br>
## v1.2.5
[Released](https://github.com/marzer/tomlplusplus/releases/tag/v1.2.5) 2020-04-24
#### Fixes:
- fixed some multi-line string parsing issues
- fixed pedantic warnings on gcc 10 and clang 11
- fixed `is_unicode_XXXXXX` functions being wrong in some cases
@ -433,21 +467,23 @@ break (hence the version number bump). Changes that might block a migration are
- fixed minor documentation issues (#26, #38) (@prince-chrismc)
#### Additions:
- added additional error message cases to the parser
- added `error_printer` example
- added `toml_generator` example
#### Changes:
- improved unicode-related codegen
- improved unicode-related codegen
<br><br>
## v1.2.3
[Released](https://github.com/marzer/tomlplusplus/releases/tag/v1.2.3) 2020-04-11
#### Fixes:
- fixed printing of inf and nan
- fixed parser not handling floats with leading '.' characters
- fixed pedantic vtable warnings on clang with -Weverything
@ -455,23 +491,25 @@ break (hence the version number bump). Changes that might block a migration are
- fixed `TOML_UNRELEASED_FEATURES` default being 1 (it should have been 0)
#### Additions:
- added `TOML_PARSER` configuration option
- added `TOML_LIB_SINGLE_HEADER` indicator
- added doxygen page for the configuration options
- added SPDX-License-Identifiers around the place
#### Changes:
- split some header files up to make future maintenance easier
- refactored and greatly simplified parser
<br><br>
## v1.2.0
[Released](https://github.com/marzer/tomlplusplus/releases/tag/v1.2.0) 2020-04-07
#### Fixes:
- fixed some parsing and printing ops being locale-dependent
- fixed some parsing errors at EOF when `TOML_EXCEPTIONS = 0`
- fixed some unreferenced variable warnings on older compilers
@ -479,23 +517,25 @@ break (hence the version number bump). Changes that might block a migration are
- fixed pkgconfig subdir being wrong
#### Additions:
- added support for implementations without `<charconv>`
- added cmake package config generator (#22) (@GiulioRomualdi)
- added build config feature option `GENERATE_CMAKE_CONFIG`
- added many new tests
<br><br>
## v1.1.0
[Released](https://github.com/marzer/tomlplusplus/releases/tag/v1.1.0) 2020-04-03
#### Fixes:
- fixed some parser error paths not returning early enough `TOML_EXCEPTIONS=0`
- fixed a number of minor documentation issues
#### Additions:
- added support for [TOML 1.0.0-rc.1](https://github.com/toml-lang/toml/releases/tag/v1.0.0-rc.1) 🎉
- added `operator[]`, `begin()`, `end()` to `toml::parse_result` for `TOML_EXCEPTIONS=0`
- added additional compilation speed improvements for `TOML_ALL_INLINE=0`
@ -504,42 +544,44 @@ break (hence the version number bump). Changes that might block a migration are
- added support for installation with meson (#16) (@ximion)
- added the array and table iterators to the `toml` namespace
<br><br>
## v1.0.0
[Released](https://github.com/marzer/tomlplusplus/releases/tag/1.0.0) 2020-03-28
#### Fixes:
- fixed minor documentation issues
#### Changes:
- refactoring of ABI-based inline namespaces
- refactoring of ABI-based inline namespaces
<br><br>
## v0.6.0
[Released](https://github.com/marzer/tomlplusplus/releases/tag/v0.6.0) 2020-03-24
#### Fixes:
- fixed minor preprocessor/macro issues
- fixed minor documentation issues
#### Additions:
- added `<cassert>` include directly in 'debug' builds when `TOML_ASSERT` isn't defined
- added Clang's `[[trivial_abi]]` attribute to `date`, `time`, `time_offset`
<br><br>
## v0.5.0
[Released](https://github.com/marzer/tomlplusplus/releases/tag/v0.5.0) 2020-03-18
#### Fixes:
- fixed crash when reaching EOF while parsing a string when exceptions are disabled
- fixed some attribute warnings in GCC
- fixed build with GCC 8.2.0 (#15) (@shdnx)
@ -548,56 +590,61 @@ break (hence the version number bump). Changes that might block a migration are
- fixed `json_formatter` type deduction on older compilers
#### Additions:
- added support for Unicode 13.0
- added support for `\xHH` escape sequences ([toml/pull/796](https://github.com/toml-lang/toml/pull/796))
- added short-form license preamble to all source files
- added build configuration option for compiling examples
<br><br>
## v0.4.3
[Released](https://github.com/marzer/tomlplusplus/releases/tag/v0.4.3) 2020-03-10
#### Fixes:
- fixed ICE in VS2019 when using `/std:c++17` instead of `/std:c++latest`
#### Additions:
- added `#error` when `TOML_EXCEPTIONS` is set to `1` but compiler exceptions were disabled
#### Changes:
- parsing performance improvements
- parsing performance improvements
<br><br>
## v0.4.0
[Released](https://github.com/marzer/tomlplusplus/releases/tag/v0.4.0) 2020-03-05
#### Fixes:
- fixed `parse_file()` failing to compile with plain string literals
- fixed tests being built when used as a meson subproject (#14) (@shdnx)
#### Additions:
- added support for compiling into DLLs on windows (`TOML_API`)
- added support for explicitly setting the `TOML_EXCEPTION` mode
- added `TOML_OPTIONAL_TYPE` customization point
- added `node::ref()` and `node_view::ref()`
<br><br>
## v0.3.0
[Released](https://github.com/marzer/tomlplusplus/releases/tag/v0.3.0) 2020-03-01
#### Fixes:
- fixed some pedantic clang warnings
- fixed some minor documentation errors
#### Additions:
- added `node::value()` and `node::value_or()`
- added `node_view::value()`
- added relops for the date/time classes
@ -605,51 +652,53 @@ break (hence the version number bump). Changes that might block a migration are
- added preliminary support for ICC
#### Removals:
- removed `<cmath>` dependency
- removed `<cmath>` dependency
<br><br>
## v0.2.1
[Released](https://github.com/marzer/tomlplusplus/releases/tag/v0.2.1) 2020-02-26
#### Fixes:
- fixed minor printing bug in `operator<<(ostream, source_position)`
- fixed minor documentation issues
#### Additions:
- added `operator<<(ostream&, parse_error)`
#### Changes:
- improved quality of error messages for boolean and inf/nan parsing
- improved quality of error messages for boolean and inf/nan parsing
<br><br>
## v0.2.0
[Released](https://github.com/marzer/tomlplusplus/releases/tag/v0.2.0) 2020-02-23
#### Fixes:
- fixed truncation of floating-point values when using ostreams
- fixed missing value deduction guides for dates and times
- fixed potential ODR issues relating to exception mode handling etc.
- fixed some documentation issues
#### Additions:
- added serialization round-trip tests
- added `node::is_number()`
- added `node_view::is_number()`
- added `node_view::value_or()`
- added hexfloat parsing support for all implementations (not just `<charconv>` ones)
<br><br>
## v0.1.0
[Released](https://github.com/marzer/tomlplusplus/releases/tag/v0.1.0) 2020-02-20
- First public release, yay! 🎉&#xFE0F;

10
CONTRIBUTING.md
View File

@ -1,6 +1,8 @@
# Contributing to toml++
Contributions are very welcome! Either by [reporting 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`.
- Your changes should compile warning-free on at least one of:
@ -12,6 +14,7 @@ If you wish to submit a PR, please be aware that:
<br>
## Regenerating toml.hpp
1. Make your changes as necessary
- 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`
@ -21,6 +24,7 @@ If you wish to submit a PR, please be aware that:
<br>
## Building and running the tests
Testing is done using [Catch2].
### Testing on Windows with Visual Studio
@ -33,6 +37,7 @@ If test discovery fails you can usually fix it by enabling
`Auto Detect runsettings Files` (settings gear icon > `Configure Run Settings`).
### Testing on Linux (and WSL)
```bash
# install ninja, meson, locales (first time only)
sudo apt update && sudo apt install -y locales python3 python3-pip ninja-build
@ -63,12 +68,13 @@ cd build-gcc-debug && ninja && ninja test \
> ℹ&#xFE0F; To ensure parity between single-header and regular versions of the library, 50% of the tests
will be compiled using one, and 50% with the other. Ensure you've regenerated toml.hpp before running tests.
> ℹ&#xFE0F; Pass `-Duse_vendored_libs=false` to meson if you wish to use the system-installed version
> ℹ&#xFE0F; Pass `-Duse_vendored_libs=false` to Meson if you wish to use the system-installed version
of Catch2 rather than the vendored one.
<br>
## Testing with the [toml-test] suite
As an optional extra you may wish to test against the 'official' test TOML test suite, [BurntSushi/toml-test]. See the
instructions at [toml-test/README](./toml-test/README.md). Note that the toml++ tests already consume tests from the
offical suite via a C++ code-generation script so you are not expected to take this extra step as part of contributing
@ -78,7 +84,5 @@ to the library.
[Test Adapter for Catch2]: https://marketplace.visualstudio.com/items?itemName=JohnnyHendriks.ext01
[reporting issues]: https://github.com/marzer/tomlplusplus/issues
[Catch2]: https://github.com/catchorg/Catch2
[meson]: https://mesonbuild.com/Getting-meson.html
[ninja]: https://github.com/ninja-build/ninja/wiki/Pre-built-Ninja-packages
[toml-test]: https://github.com/BurntSushi/toml-test
[BurntSushi/toml-test]: https://github.com/BurntSushi/toml-test

70
README.md
View File

@ -8,7 +8,7 @@
[![Gitter](docs/images/badge-gitter.svg)](https://gitter.im/marzer/tomlplusplus)
====
# toml++ homepage
## toml++ homepage
<p align="center">
<strong>✨&#xFE0F; This README is fine, but the <a href="https://marzer.github.io/tomlplusplus/">toml++ homepage</a> is better. ✨&#xFE0F;</strong>
@ -16,14 +16,14 @@
<br>
# Library features
## Library features
- Header-only (optional!)
- Supports the latest [TOML] release ([v1.0.0]), plus optional support for some unreleased TOML features
- Passes all tests in the [toml-test](https://github.com/BurntSushi/toml-test) 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 char8_t strings)
- C++17 (plus some C++20 features where available, e.g. experimental support for [char8_t] strings)
- Doesn't require RTTI
- Works with or without exceptions
- Tested on Clang (6+), GCC (7+) and MSVC (VS2019)
@ -31,12 +31,13 @@
<br>
# Basic usage
## Basic usage
> ℹ&#xFE0F; _The following example favours brevity. If you'd prefer full API documentation and lots of specific code snippets
instead, visit the project [homepage]_
Given a [TOML] file `configuration.toml` containing the following:
```toml
[library]
name = "toml++"
@ -45,7 +46,9 @@ authors = ["Mark Gillard <mark.gillard@outlook.com.au>"]
[dependencies]
cpp = 17
```
Reading it in C++ is easy with toml++:
```cpp
#include <toml.hpp>
@ -87,37 +90,44 @@ std::cout << toml::json_formatter{ config } << "\n";
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 [API documentation].
<br>
# Adding toml++ to your project
## Adding toml++ to your project
`toml++` comes in two flavours: Single-header and Regular. The API is the same for both.
### 🍦&#xFE0F; Single-header flavour
1. Drop [`toml.hpp`] wherever you like in your source tree
2. There is no step two
### 🍨&#xFE0F; Regular flavour
1. Clone the repository
2. Add `tomlplusplus/include` to your include paths
3. `#include <toml++/toml.h>`
### Conan
Add `tomlplusplus/3.2.0` to your conanfile.
### DDS
Add `tomlpp` to your `package.json5`, e.g.:
```
```plaintext
depends: [
'tomlpp^3.2.0',
]
```
> ℹ&#xFE0F; _[What is DDS?](https://dds.pizza/)_
### Tipi.build
`tomlplusplus` can be easily used in [tipi.build](https://tipi.build) projects by adding the following entry to your `.tipi/deps`:
```json
@ -127,26 +137,30 @@ depends: [
```
### Vcpkg
```
```plaintext
vcpkg install tomlplusplus
```
### Meson
You can install the wrap with:
```
```plaintext
meson wrap install tomlplusplus
```
After that, you can use it like a regular dependency:
```
```meson
tomlplusplus_dep = dependency('tomlplusplus')
```
You can also add it as a subproject directly.
### CMake FetchContent
```
```cmake
include(FetchContent)
FetchContent_Declare(
tomlplusplus
@ -155,31 +169,36 @@ FetchContent_Declare(
)
FetchContent_MakeAvailable(tomlplusplus)
```
> ℹ&#xFE0F; _[What is FetchContent?](https://cmake.org/cmake/help/latest/module/FetchContent.html)_
### Git submodules
```
```plaintext
git submodule add --depth 1 https://github.com/marzer/tomlplusplus.git tomlplusplus
git config -f .gitmodules submodule.tomlplusplus.shallow true
```
> ⚠&#xFE0F; The toml++ repository has some submodules of its own, but **they are only used for testing**!
> You should **not** use the `--recursive` option for regular library consumption.
### 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
[make a pull request](./CONTRIBUTING.md).
### 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 [CONTRIBUTING] for information.
<br>
# Configuration
## 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++.
@ -208,7 +227,8 @@ linking incompatible combinations together._
<br>
# TOML Language Support
## 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 [TOML master] and some sane cherry-picks from the
[TOML issues list] where the discussion strongly indicates inclusion in a near-future release.
@ -217,6 +237,7 @@ The library advertises the most recent numbered language version it fully suppor
defines `TOML_LANG_MAJOR`, `TOML_LANG_MINOR` and `TOML_LANG_PATCH`.
### **Unreleased language features:**
- [#516]: Allow newlines and trailing commas in inline tables
- [#562]: Allow hex floating-point values
- [#644]: Support `+` in key names
@ -229,7 +250,9 @@ defines `TOML_LANG_MAJOR`, `TOML_LANG_MINOR` and `TOML_LANG_PATCH`.
> ℹ&#xFE0F; _`#define TOML_ENABLE_UNRELEASED_FEATURES 1` to enable these features (see [Configuration](#Configuration))._
### 🔹&#xFE0F; **TOML v1.0.0:**
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
@ -237,23 +260,26 @@ All features supported, including:
- [#766]: Allow comments before commas in arrays
### 🔹&#xFE0F; **TOML v0.5.0:**
All features supported.
<br>
# Contributing
## 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.
<br>
# License and Attribution
## 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]'.
### With thanks to:
- **[@beastle9end](https://github.com/beastle9end)** - Made Windows.h include bypass
- **[@bjadamson](https://github.com/bjadamson)** - Reported some bugs and helped design a new feature
- **[@bobfang1992](https://github.com/bobfang1992)** - Reported a bug and created a [wrapper in python](https://github.com/bobfang1992/pytomlpp)
@ -281,22 +307,21 @@ UTF-8 decoding is performed using a state machine based on Bjoern Hoehrmann's '[
<br>
# Contact
## 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:
- Gitter: [marzer/tomlplusplus](https://gitter.im/marzer/tomlplusplus) ("Discord for repos")
- Twitter: [marzer8789](https://twitter.com/marzer8789)
- Email: [mark.gillard@outlook.com.au](mailto:mark.gillard@outlook.com.au)
- Facebook: [marzer](https://www.facebook.com/marzer)
- LinkedIn: [marzer](https://www.linkedin.com/in/marzer/)
[API documentation]: https://marzer.github.io/tomlplusplus/
[homepage]: https://marzer.github.io/tomlplusplus/
[unreleased TOML language features]: #unreleased-language-features
[most recently-released version]: https://github.com/toml-lang/toml/releases
[numbered version]: https://github.com/toml-lang/toml/releases
[char8_t]: https://en.cppreference.com/w/cpp/keyword/char8_t
[TOML]: https://toml.io/
[TOML master]: https://github.com/toml-lang/toml/blob/master/README.md
@ -307,14 +332,12 @@ though you're welcome to reach out via other means. In order of likely response
[Flexible and Economical UTF-8 Decoder]: http://bjoern.hoehrmann.de/utf-8/decoder/dfa/
[cpp_compilers]: https://en.cppreference.com/w/cpp/compiler_support
[reporting issues]: https://github.com/marzer/tomlplusplus/issues/new/choose
[feature request]: https://github.com/marzer/tomlplusplus/issues/new/choose
[issues]: https://github.com/marzer/tomlplusplus/issues
[#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
@ -325,5 +348,4 @@ though you're welcome to reach out via other means. In order of likely response
[#891]: https://github.com/toml-lang/toml/pull/891
[something better than std::optional]: https://github.com/TartanLlama/optional
[m.css]: https://mcss.mosra.cz/documentation/doxygen
[toml.hpp]: https://raw.githubusercontent.com/marzer/tomlplusplus/master/toml.hpp
[`toml.hpp`]: https://raw.githubusercontent.com/marzer/tomlplusplus/master/toml.hpp