mirror/tomlplusplus
1
0
Fork 0
mirror of https://github.com/marzer/tomlplusplus.git synced 2024-09-15 15:13:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

documentation improvements

Browse Source 
- updated TOML links to new toml.io website
- refactored the main page
This commit is contained in:
Mark Gillard 2020-06-24 14:28:20 +03:00
parent 00a8d14a49
commit 464d3d13cc
9 changed files with 139 additions and 134 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CONTRIBUTING.md
View File

@ -13,7 +13,7 @@ If you wish to submit a PR, please be aware that:
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`
3. Run `python/generate_single_header.py`
2. Run `python/generate_single_header.py`
<br>

23
README.md
View File

@ -9,13 +9,13 @@
====
- Header-only
- [TOML v1.0.0-rc.1], plus optional support for some [unreleased TOML language features]
- Supports the latest [TOML] release ([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 Clang (7+), GCC (7+) and MSVC (VS2019)
- Tested on x64, x86 and ARM
<br>
@ -24,7 +24,7 @@
> ℹ _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](https://marzer.github.io/tomlplusplus/)**_
Given a TOML file `configuration.toml` containing the following:
Given a [TOML] file `configuration.toml` containing the following:
```toml
[library]
name = "toml++"
@ -33,7 +33,7 @@ authors = ["Mark Gillard <mark.gillard@outlook.com.au>"]
[dependencies]
cpp = 17
```
Reading it in C++ is easy with `toml++`:
Reading it in C++ is easy with toml++:
```cpp
#include <toml.hpp>
#include <fstream> //required for toml::parse_file()
@ -93,8 +93,9 @@ know by making a [feature request]. Better still, if you have the skills and mot
welcome a pull request with a smile and open arms!
### Conan
`toml++` is available through the [Conan-Center-Index](https://github.com/conan-io/conan-center-index). You simply need to add `tomlplusplus/1.2.3` to your _conanfile_ to include this in your project. The default options are set for the single-header
flavour, however specifying the option `"multiple_headers": True` is available.
`toml++` is available through the [Conan-Center-Index](https://github.com/conan-io/conan-center-index). You simply need
to add `tomlplusplus/1.2.3` to your _conanfile_ to include this in your project. The default options are set for the
single-header flavour, however specifying the option `"multiple_headers": True` is available.
<br>
@ -124,7 +125,7 @@ linking incompatible combinations together._
<br>
# TOML Language Support
At any given time `toml++` aims to implement whatever the [most recently-released version] of TOML is, with opt-in
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.
@ -161,7 +162,7 @@ If you wish to submit a pull request, please see [CONTRIBUTING] for all the deta
# License and Attribution
`toml++` is licensed under the terms of the MIT license - see [LICENSE].
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]'.
@ -172,7 +173,7 @@ UTF-8 decoding is performed using a state machine based on Bjoern Hoehrmann's '[
- **[@mosra](https://github.com/mosra)** - Created the awesome [m.css] used to generate the API docs
- **[@ned14](https://github.com/ned14)** - Reported a bunch of bugs and helped design some new features
- **[@okureta](https://github.com/okureta)** - Reported a bug
- **[@prince-chrismc](https://github.com/prince-chrismc)** - Added `toml++` to ConanCenter, and fixed some typos
- **[@prince-chrismc](https://github.com/prince-chrismc)** - Added toml++ to ConanCenter, and fixed some typos
- **[@rbrugo](https://github.com/rbrugo)** - Helped design a new feature
- **[@shdnx](https://github.com/shdnx)** - Fixed a bug on GCC 8.2.0 and some meson config issues
- **[@traversaro](https://github.com/traversaro)** - Added vcpkg support and reported a bunch of bugs
@ -196,10 +197,10 @@ though you're welcome to reach out via other means. In order of likely response
[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
[TOML issues list]: https://github.com/toml-lang/toml/issues
[TOML v1.0.0-rc.1]: https://github.com/toml-lang/toml/blob/master/versions/en/toml-v1.0.0-rc.1.md
[v1.0.0-rc.1]: https://github.com/toml-lang/toml/blob/master/versions/en/toml-v1.0.0-rc.1.md
[v1.0.0-rc.1]: https://toml.io/en/v1.0.0-rc.1
[CONTRIBUTING]: ./CONTRIBUTING.md
[LICENSE]: ./LICENSE
[Flexible and Economical UTF-8 Decoder]: http://bjoern.hoehrmann.de/utf-8/decoder/dfa/

214
include/toml++/toml.h
View File

@ -26,7 +26,6 @@
#include "toml_formatter.h"
#include "toml_default_formatter.h"
#include "toml_json_formatter.h"
#if TOML_PARSER
#include "toml_parse_error.h"
#include "toml_utf8_streams.h"
@ -39,15 +38,12 @@
#include "toml_table.hpp"
#include "toml_default_formatter.hpp"
#include "toml_json_formatter.hpp"
#if TOML_PARSER
#include "toml_parser.hpp"
#endif // TOML_PARSER
#if !TOML_ALL_INLINE
#include "toml_instantiations.hpp"
#endif // !TOML_ALL_INLINE
#endif // TOML_IMPLEMENTATION
// macro hygiene
@ -109,14 +105,15 @@
///////////////////////////////////////////////////////////////////////
///
/// \section mainpage-features Features
/// - [TOML v1.0.0-rc.1](https://github.com/toml-lang/toml/blob/master/versions/en/toml-v1.0.0-rc.1.md),
/// plus optional support for some unreleased TOML features
/// - Header-only
/// - Supports the latest [TOML](https://toml.io/) release ([v1.0.0-rc.1](https://toml.io/en/v1.0.0-rc.1)), plus
/// optional support for some unreleased TOML 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)
/// - First-class support for serializing to JSON
/// - Tested on Clang (7+), GCC (7+) and MSVC (VS2019)
/// - Tested on x64, x86 and ARM
///
///////////////////////////////////////////////////////////////////////
@ -124,13 +121,13 @@
/// \section mainpage-adding-lib Adding toml++ to your project
/// It's header-only library so really all you have to do is clone
/// [the repository](https://github.com/marzer/tomlplusplus/) from GitHub and set your include paths.
/// There's some minor configuration you can do to customize some basic library functionality, but that's totally
/// There's some minor configuration you can do to customize some basic library functionality, but it's totally
/// optional.
/// \see \ref configuration
///
///////////////////////////////////////////////////////////////////////
///
/// \section mainpage-api-documentation API Documentation
/// \section mainpage-api-documentation API documentation
/// You're looking at it! Browse the docs using the links at the top of the page.
/// You can search from anywhere by pressing the TAB key.
///
@ -140,16 +137,13 @@
///
///////////////////////////////////
///
/// \subsection mainpage-example-parsing-files Parsing TOML files
/// toml++ works whether you have exceptions enabled or not. For the most part the usage is the same,
/// the main difference being how parsing errors are reported to the caller. When exceptions are enabled
/// a successful call to a parsing function simply returns a toml::table, whereas a failed call sees a toml::parse_error
/// thrown directly from the site of the error:
/// \subsection mainpage-example-parsing-files Parsing files
/// Call toml::parse_file() and work with the toml::table you get back, or handle any toml::parse_error that gets thrown:
///
/// \cpp
/// #include <iostream>
/// #include <fstream> //required for parse_file()
/// #include <toml++/toml.h>
/// using namespace std::string_view_literals;
///
/// int main()
/// {
@ -160,86 +154,32 @@
/// }
/// catch (const toml::parse_error& err)
/// {
/// std::cerr
/// << "Error parsing file '" << *err.source().path
/// << "':\n" << err.description()
/// << "\n (" << err.source().begin << ")\n";
/// std::cerr << "Parsing failed:\n" << err << "\n";
/// return 1;
/// }
///
///
/// do_stuff_with_your_config(tbl);
///
/// return 0;
/// }
///
/// \ecpp
///
/// When exceptions are disabled parsing functions return a toml::parse_result instead and it is up to the caller
/// to check if parsing has been successful by examining the return value:
/// \cpp
/// #include <iostream>
/// #include <fstream> //required for parse_file()
/// #include <toml++/toml.h>
/// using namespace std::string_view_literals;
///
/// int main()
/// {
/// toml::parse_result tbl = toml::parse_file("configuration.toml");
/// if (!tbl)
/// {
/// std::cerr
/// << "Error parsing file '" << *tbl.error().source().path
/// << "':\n" << tbl.error().description()
/// << "\n (" << tbl.error().source().begin << ")\n";
/// return 1;
/// }
///
/// do_stuff_with_your_config(tbl); //toml::parse_result is convertible to toml::table
/// return 0;
/// }
/// \ecpp
///
/// Instances of toml::parse_error can be printed directly to streams:
/// \cpp
/// try
/// {
/// auto tbl = toml::parse("enabled = trUe"sv); //fails; TOML booleans are case-sensitive
/// }
/// catch (const toml::parse_error & err)
/// {
/// std::cerr << "Parsing failed:\n" << err << "\n";
/// return 1;
/// }
/// \ecpp
///
/// \out
/// Parsing failed:
/// Encountered unexpected character while parsing boolean; expected 'true', saw 'trU'
/// (error occurred at line 1, column 13)
/// \eout
///
/// If the default error formatting is not be suitable for your use-case you can access the error's
/// toml::source_region and description directly from the error object (as in the examples above).
///
/// \m_class{m-note m-warning}
///
/// \parblock
/// <h3>Don't forget &lt;fstream&gt;!</h3>
/// <h3>Don't forget [code]#include &lt;fstream&gt;[/code]!</h3>
/// Not everyone who uses the library is going to work directly from files, so not everybody is forced to pay
/// the compilation overhead of including `<fstream>`. You need to explicitly include it if you're going to be calling
/// toml::parse_file().
/// \endparblock
///
/// \see
/// - toml::parse_file()
/// - toml::parse_result
/// - toml::parse_error
/// - toml::source_region
/// - toml::source_position
///
///////////////////////////////////
///
/// \subsection mainpage-example-parsing-strings Parsing TOML directly from strings and streams
/// Strings and std::istreams can be read directly using toml::parse():
/// \subsection mainpage-example-parsing-strings Parsing strings and iostreams
///
/// Call toml::parse() and work with the toml::table you get back, or handle any toml::parse_error that gets thrown:
///
/// \cpp
/// #include <iostream>
/// #include <sstream>
@ -248,50 +188,112 @@
///
/// int main()
/// {
/// static constexpr auto source = R"(
/// static constexpr std::string_view some_toml = R"(
/// [library]
/// name = "toml++"
/// authors = ["Mark Gillard <mark.gillard@outlook.com.au>"]
///
/// [dependencies]
/// cpp = 17
/// )"sv;
///
/// // parse directly from a string view:
/// {
/// auto tbl = toml::parse(source);
/// std::cout << tbl << "\n";
/// }
///
/// // parse from a string stream:
/// {
/// std::stringstream ss{ std::string{ source } };
/// auto tbl = toml::parse(ss);
/// std::cout << tbl << "\n";
/// try
/// {
/// // parse directly from a string view:
/// {
/// auto tbl = toml::parse(some_toml);
/// std::cout << tbl << "\n";
/// }
///
/// // parse from a string stream:
/// {
/// std::stringstream ss{ std::string{ some_toml } };
/// auto tbl = toml::parse(ss);
/// std::cout << tbl << "\n";
/// }
/// }
/// catch (const toml::parse_error& err)
/// {
/// std::cerr << "Parsing failed:\n" << err << "\n";
/// return 1;
/// }
///
/// return 0;
/// }
/// \ecpp
///
/// \out
/// [dependencies]
/// cpp = 17
///
/// [library]
/// authors = ["Mark Gillard <mark@notarealwebsite.com>"]
/// authors = ["Mark Gillard <mark.gillard@outlook.com.au>"]
/// cpp = 17
/// name = "toml++"
///
/// ... exactly as above, but twice
/// ... twice
/// \eout
///
/// The error-handling semantics are the same as for toml::parse_file.
///
/// \see toml::parse()
///
///////////////////////////////////
///
/// \subsection mainpage-example-manipulations Traversing and manipulating data
/// \subsection mainpage-example-parsing-without-exceptions Parsing without using exceptions
/// Can't (or won't) use exceptions? That's fine too. You can disable exceptions in your compiler flags and/or
/// explicitly disable the library's use of them by setting the option \ref TOML_EXCEPTIONS to `0`. In either case,
/// the parsing functions return a toml::parse_result instead of a toml::table:
///
/// \cpp
/// #include <iostream>
/// #include <fstream>
///
/// #define TOML_EXCEPTIONS 0 // only necessary if you've left them enabled in your compiler
/// #include <toml++/toml.h>
///
/// int main()
/// {
/// toml::parse_result result = toml::parse_file("configuration.toml");
/// if (!result)
/// {
/// std::cerr << "Parsing failed:\n" << result.error() << "\n";
/// return 1;
/// }
///
/// do_stuff_with_your_config(result); //toml::parse_result is convertible to toml::table
/// return 0;
/// }
/// \ecpp
///
///////////////////////////////////
///
/// \subsection mainpage-example-custom-error-formatting Custom error formatting
/// The examples above use an overloaded `operator<<` with ostreams to print basic error messages, and look like this:
/// \out
/// Encountered unexpected character while parsing boolean; expected 'true', saw 'trU'
/// (error occurred at line 1, column 13)
/// \eout
///
/// In order to keep the library as small as possible I haven't bent over backwards to support things like custom
/// colouring of the text in TTY environments, et cetera. That being said, the library provides the requisite information
/// for you to build these yourself if necessary via toml::parse_error's source() and description() members:
///
/// \cpp
/// toml::table tbl;
/// try
/// {
/// tbl = toml::parse_file("configuration.toml");
/// }
/// catch (const toml::parse_error& err)
/// {
/// std::cerr
/// << "Error parsing file '" << *err.source().path
/// << "':\n" << err.description()
/// << "\n (" << err.source().begin << ")\n";
/// return 1;
/// }
/// \ecpp
///
/// \see
/// - toml::parse_error
/// - toml::source_region
/// - toml::source_position
///
///////////////////////////////////
///
/// \subsection mainpage-example-manipulations Working with TOML data
/// A TOML document is a tree of values, arrays and tables, represented as the toml::value, toml::array
/// and toml::table, respectively. All three inherit from toml::node, and can be easily accessed via
/// the toml::node_view:
@ -444,12 +446,12 @@
///////////////////////////////////
///
/// \subsection mainpage-example-speed-up-compilation Speeding up compilation
/// Because `toml++` is a header-only library of nontrivial size you might find that compilation times noticeably
/// Because toml++ is a header-only library of nontrivial size you might find that compilation times noticeably
/// increase after you add it to your project, especially if you add the library's header somewhere that's visible from
/// a large number of translation units. You can counter this by disabling 'all inline' mode and explicitly controlling
/// where the library's implementation is compiled.
///
/// <strong>Step 1: Set `TOML_ALL_INLINE` to `0` before including `toml++`</strong>
/// <strong>Step 1: Set \ref TOML_ALL_INLINE to `0` before including toml++</strong>
///
/// This must be the same everywhere, so either set it as a global `#define` in your build system, or
/// do it manually before including toml++ in some global header that's used everywhere in your project:
@ -460,7 +462,7 @@
/// #include <toml.hpp>
/// \ecpp
///
/// <strong>Step 2: Define `TOML_IMPLEMENTATION` before including `toml++` in one specific translation unit</strong>
/// <strong>Step 2: Define `TOML_IMPLEMENTATION` before including toml++ in one specific translation unit</strong>
///
/// \cpp
/// // some_code_file.cpp
@ -471,6 +473,8 @@
///
/// Additionally, if all you need to do is serialize some code-generated TOML and don't actually need the parser at all,
/// you can `#define TOML_PARSER 0`.
///
/// \see \ref configuration
///
///////////////////////////////////////////////////////////////////////
///

3
include/toml++/toml_parse_error.h
View File

@ -33,7 +33,7 @@ namespace toml
TOML_ABI_NAMESPACE_START(noex)
/// \brief An error thrown/returned when parsing fails.
/// \brief An error generated when parsing fails.
///
/// \remarks This class inherits from std::runtime_error when exceptions are enabled.
/// The public interface is the same regardless of exception mode.
@ -63,6 +63,7 @@ namespace toml
/// \brief Returns a textual description of the error.
/// \remark The backing string is guaranteed to be null-terminated.
[[nodiscard]]
std::string_view description() const noexcept
{

5
include/toml++/toml_parser.h
View File

@ -480,8 +480,7 @@ namespace toml
/// \returns <strong><em>With exceptions:</em></strong> A toml::table. <br>
/// <strong><em>Without exceptions:</em></strong> A toml::parse_result detailing the parsing outcome.
///
/// \attention You must `#include <fstream>` to use this function (toml++
/// does not transitively include it for you).
/// \attention You must `#include <fstream>` to use this function (toml++ does not transitively include it for you).
template <typename Char, typename StreamChar = char>
[[nodiscard]]
TOML_EXTERNAL_LINKAGE
@ -566,7 +565,7 @@ namespace toml
TOML_ABI_NAMESPACE_END // TOML_EXCEPTIONS
/// \brief Convenience literal operators for working with TOML++.
/// \brief Convenience literal operators for working with toml++.
///
/// \detail This namespace exists so you can safely hoist the UDL operators into another scope
/// without dragging in everything in the toml namespace: \cpp

6
include/toml++/toml_preprocessor.h
View File

@ -183,7 +183,7 @@
#if TOML_CPP_VERSION < 201103L
#error toml++ requires C++17 or higher. For a TOML library supporting pre-C++11 see https://github.com/ToruNiina/Boost.toml
#elif TOML_CPP_VERSION < 201703L
#error toml++ requires C++17 or higher. For a TOML library supporting C++11 see https://github.com/skystrife/cpptoml
#error toml++ requires C++17 or higher. For a TOML library supporting C++11 see https://github.com/ToruNiina/toml11
#elif TOML_CPP_VERSION >= 202600L
#define TOML_CPP 26
#elif TOML_CPP_VERSION >= 202300L
@ -395,7 +395,7 @@ TOML_POP_WARNINGS
/// \addtogroup configuration Library Configuration
/// \brief Preprocessor macros for configuring library functionality.
/// \detail Define these before including `toml++` to alter the way it functions.
/// \detail Define these before including toml++ to alter the way it functions.
/// \remarks Some of these options have ABI implications; inline namespaces are used to prevent
/// you from trying to link incompatible combinations together.
/// @{
@ -437,7 +437,7 @@ TOML_POP_WARNINGS
#define TOML_CONFIG_HEADER
/// \def TOML_CONFIG_HEADER
/// \brief An additional header to include before any other `toml++` header files.
/// \brief An additional header to include before any other toml++ header files.
/// \detail Not defined by default.

10
python/generate_documentation.py
View File

@ -293,10 +293,10 @@ class RegexReplacer(object):
# allows the injection of <div> and <span> tags using [div] and [span] proxies.
# allows the injection of custom tags using square-bracketed proxies.
class CustomTagsFix(object):
__expression = re.compile(r"\[\s*(span|div)(.*?)\s*\](.*?)\[\s*/\s*\1\s*\]", re.I)
__allowedNames = ['dd', 'p']
__expression = re.compile(r"\[\s*(span|div|code|pre)(.*?)\s*\](.*?)\[\s*/\s*\1\s*\]", re.I)
__allowedNames = ['dd', 'p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6']
@classmethod
def __substitute(cls, m):
@ -474,9 +474,9 @@ class IndexPageFix(object):
'https://en.cppreference.com/w/cpp/compiler_support'
),
(
'TOML',
'TOML v1.0.0-rc.1',
'badge-TOML.svg',
'https://github.com/toml-lang/toml/blob/master/README.md'
'https://toml.io/en/v1.0.0-rc.1'
),
(None, None, None), # <br>
(

4
python/generate_single_header.py
View File

@ -147,8 +147,8 @@ that contributed to this header can be found at the beginnings and ends of the c
preamble.append('''
TOML language specifications:
Latest: https://github.com/toml-lang/toml/blob/master/README.md
v1.0.0-rc.1: https://github.com/toml-lang/toml/blob/master/versions/en/toml-v1.0.0-rc.1.md
v0.5.0: https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.5.0.md''')
v1.0.0-rc.1: https://toml.io/en/v1.0.0-rc.1
v0.5.0: https://toml.io/en/v0.5.0''')
preamble.append(read_all_text_from_file(path.join(get_script_folder(), '..', 'LICENSE')))
# write the output file

6
toml.hpp
View File

@ -17,8 +17,8 @@
//
// TOML language specifications:
// Latest: https://github.com/toml-lang/toml/blob/master/README.md
// v1.0.0-rc.1: https://github.com/toml-lang/toml/blob/master/versions/en/toml-v1.0.0-rc.1.md
// v0.5.0: https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.5.0.md
// v1.0.0-rc.1: https://toml.io/en/v1.0.0-rc.1
// v0.5.0: https://toml.io/en/v0.5.0
//
//----------------------------------------------------------------------------------------------------------------------
//
@ -213,7 +213,7 @@
#if TOML_CPP_VERSION < 201103L
#error toml++ requires C++17 or higher. For a TOML library supporting pre-C++11 see https://github.com/ToruNiina/Boost.toml
#elif TOML_CPP_VERSION < 201703L
#error toml++ requires C++17 or higher. For a TOML library supporting C++11 see https://github.com/skystrife/cpptoml
#error toml++ requires C++17 or higher. For a TOML library supporting C++11 see https://github.com/ToruNiina/toml11
#elif TOML_CPP_VERSION >= 202600L
#define TOML_CPP 26
#elif TOML_CPP_VERSION >= 202300L