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 
- moved the main page to a separate dox file
- added integration section to homepage
- improved some of the examples
- formatting fixes
- added note about python wrapper (closes #36)
This commit is contained in:
Mark Gillard 2020-07-02 20:17:23 +03:00
parent f52949a481
commit 51f64fd08d
13 changed files with 634 additions and 479 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -1,3 +1,4 @@
emojis.json
UnicodeData.txt
meson-info/
meson-logs/

14
README.md
View File

@ -8,6 +8,16 @@
[![Mentioned in Awesome C++](docs/badge-awesome.svg)](https://github.com/fffaraz/awesome-cpp)
====
# toml++ homepage
<p align="center">
<strong>✨ This README is fine, but the <a href="https://marzer.github.io/tomlplusplus/">toml++ homepage</a> is better. ✨</strong>
</p>
<br>
# Library features
- Header-only
- 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)
@ -22,7 +32,7 @@
# 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](https://marzer.github.io/tomlplusplus/)**_
> ℹ _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
@ -94,7 +104,7 @@ 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
to add `tomlplusplus/1.3.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>

5
docs/Doxyfile
View File

@ -44,7 +44,11 @@ ALIASES = \
"ecpp=@endcode" \
"out=@code{.shell-session}" \
"eout=@endcode" \
"bash=@code{.sh}" \
"ebash=@endcode" \
"detail=@details" \
"gh{1}=<a href=\"https://github.com/\1\">\1</a>"\
"gh2{2}=<a href=\"https://github.com/\1\">\2</a>"\
"m_div{1}=@xmlonly<mcss:div xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:class=\"\1\">@endxmlonly" \
"m_enddiv=@xmlonly</mcss:div>@endxmlonly" \
"m_span{1}=@xmlonly<mcss:span xmlns:mcss=\"http://mcss.mosra.cz/doxygen/\" mcss:class=\"\1\">@endxmlonly" \
@ -132,6 +136,7 @@ WARN_LOGFILE = ./doc/doxygen_warnings.log
# Configuration options related to the input files
#---------------------------------------------------------------------------
INPUT = ../include
INPUT += ../docs
INPUT_ENCODING = UTF-8
FILE_PATTERNS = *.h \
*.dox

504
docs/main_page.dox Normal file
View File

@ -0,0 +1,504 @@
///
/// \mainpage toml++
/// \image html banner_small.png width=1280px
/// \tableofcontents
///
//////////////////////////////////////////////////////////////////////
///
/// \section mainpage-features Features
/// - 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
/// - Supports serializing to JSON
/// - Proper UTF-8 handling (incl. BOM)
/// - C++17 (plus some C++20 features where available, e.g. experimental support for char8_t strings)
/// - Header-only (optional!)
/// - Doesn't require RTTI
/// - Works with or without exceptions
/// - Tested on Clang (7+), GCC (7+) and MSVC (VS2019)
/// - Tested on x64, x86 and ARM
///
//////////////////////////////////////////////////////////////////////
///
/// \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.
///
//////////////////////////////////////////////////////////////////////
///
/// \section mainpage-example Basic examples
///
//////////////////////////////////
///
/// \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>
///
/// int main()
/// {
/// toml::table tbl;
/// try
/// {
/// tbl = toml::parse_file("configuration.toml");
/// }
/// catch (const toml::parse_error& err)
/// {
/// std::cerr << "Parsing failed:\n" << err << "\n";
/// return 1;
/// }
///
/// do_stuff_with_your_config(tbl);
///
/// return 0;
/// }
///
/// \ecpp
///
/// \m_class{m-note m-warning}
///
/// \parblock
/// <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::table
/// - toml::parse_error
///
//////////////////////////////////
///
/// \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>
/// #include <toml++/toml.h>
/// using namespace std::string_view_literals;
///
/// int main()
/// {
/// static constexpr std::string_view some_toml = R"(
/// [library]
/// name = "toml++"
/// authors = ["Mark Gillard <mark.gillard@outlook.com.au>"]
/// cpp = 17
/// )"sv;
///
/// try
/// {
/// // parse directly from a string view:
/// {
/// toml::table tbl = toml::parse(some_toml);
/// std::cout << tbl << "\n";
/// }
///
/// // parse from a string stream:
/// {
/// std::stringstream ss{ std::string{ some_toml } };
/// toml::table 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
/// [library]
/// authors = ["Mark Gillard <mark.gillard@outlook.com.au>"]
/// cpp = 17
/// name = "toml++"
///
/// ... twice
/// \eout
///
/// \see
/// - toml::parse_file()
/// - toml::table
/// - toml::parse_error
///
//////////////////////////////////
///
/// \subsection mainpage-example-parsing-without-exceptions Handling errors without 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
/// Error while parsing key: expected bare key starting character or string delimiter, saw '?'
/// (error occurred at line 2, column 5)
/// \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:
/// \cpp
/// #include <iostream>
/// #include <toml++/toml.h>
/// using namespace std::string_view_literals;
///
/// int main()
/// {
/// static constexpr auto source = R"(
/// str = "hello world"
///
/// numbers = [ 1, 2, 3, "four", 5.0 ]
/// vegetables = [ "tomato", "onion", "mushroom", "lettuce" ]
/// minerals = [ "quartz", "iron", "copper", "diamond" ]
///
/// [animals]
/// cats = [ "tiger", "lion", "puma" ]
/// birds = [ "macaw", "pigeon", "canary" ]
/// fish = [ "salmon", "trout", "carp" ]
///
/// )"sv;
/// toml::table tbl = toml::parse(source);
///
/// // different ways of directly querying data
/// std::optional<std::string_view> str1 = tbl["str"].value<std::string_view>();
/// std::optional<std::string> str2 = tbl["str"].value<std::string>();
/// std::string_view str3 = tbl["str"].value_or("");
/// std::string str4 = tbl["str"].value_or(std::string{});
/// std::string& str5 = tbl["str"].ref<std::string>(); // ~~dangerous~~, but fast
///
/// std::cout << *str1 << "\n";
/// std::cout << *str2 << "\n";
/// std::cout << str3 << "\n";
/// std::cout << str4 << "\n";
/// std::cout << str5 << "\n";
///
/// // get a toml::node_view of the element 'numbers' using operator[]
/// auto numbers = tbl["numbers"];
/// std::cout << "table has 'numbers': " << !!numbers << "\n";
/// std::cout << "numbers is an: " << numbers.type() << "\n";
/// std::cout << "numbers: " << numbers << "\n";
///
/// // get the underlying array object to do some more advanced stuff
/// if (toml::array* arr = numbers.as_array())
/// {
/// for (toml::node& elem : *arr)
/// {
/// // visitation helps deal with the polymorphic nature of TOML data
/// elem.visit([](auto&& el) noexcept
/// {
/// if constexpr (toml::is_number<decltype(el)>)
/// (*el)++;
/// else if constexpr (toml::is_string<decltype(el)>)
/// el = "five"sv;
/// });
/// }
///
/// // arrays are very similar to std::vector
/// arr->push_back(7);
/// arr->emplace_back<toml::array>(8, 9);
/// std::cout << "numbers: " << numbers << "\n";
/// }
///
/// // node-views can be chained to quickly query deeper
/// std::cout << "cats: " << tbl["animals"]["cats"] << "\n";
/// std::cout << "fish[1]: " << tbl["animals"]["fish"][1] << "\n";
///
/// // ...even if the element doesn't exist
/// std::cout << "dinosaurs: " << tbl["animals"]["dinosaurs"] << "\n"; //no dinosaurs :(
///
/// return 0;
/// }
/// \ecpp
///
/// \out
/// hello world
/// hello world
/// hello world
/// hello world
/// hello world
/// table has 'numbers': true
/// numbers is an: array
/// numbers: [1, 2, 3, "four", 5.0]
/// numbers: [2, 3, 4, "five", 6.0, 7, [8, 9]]
/// cats: ["tiger", "lion", "puma"]
/// fish[1]: "trout"
/// dinosaurs:
/// \eout
///
/// \see
/// - toml::node
/// - toml::node_view
/// - toml::value
/// - toml::array
/// - toml::table
///
//////////////////////////////////
///
/// \subsection mainpage-example-serialization Serializing as TOML and JSON
/// All toml++ data types have overloaded `operator<<` for ostreams, so 'serializing' a set of TOML data to actual
/// TOML is done just by printing it to an ostream. Converting it to JSON is done in the same way,
/// but via a toml::json_formatter.
/// \cpp
/// #include <iostream>
/// #include <toml++/toml.h>
///
/// int main()
/// {
/// auto tbl = toml::table{{
/// { "lib", "toml++" },
/// { "cpp", toml::array{ 17, 20, "and beyond" } },
/// { "toml", toml::array{ "1.0.0-rc.1", "and beyond" } },
/// { "repo", "https://github.com/marzer/tomlplusplus/" },
/// { "author", toml::table{{
/// { "name", "Mark Gillard" },
/// { "github", "https://github.com/marzer" },
/// { "twitter", "https://twitter.com/marzer8789" }
/// }}
/// },
/// }};
///
/// // serializing as TOML
/// std::cout << "###### TOML ######" << "\n\n";
/// std::cout << tbl << "\n\n";
///
/// // serializing as JSON using toml::json_formatter:
/// std::cout << "###### JSON ######" << "\n\n";
/// std::cout << toml::json_formatter{ tbl } << "\n\n";
/// return 0;
/// }
/// \ecpp
///
/// \out
/// ###### TOML ######
///
/// cpp = [17, 20, "and beyond"]
/// lib = "toml++"
/// repo = "https://github.com/marzer/tomlplusplus/"
/// toml = ["1.0.0-rc.1", "and beyond"]
///
/// [author]
/// github = "https://github.com/marzer"
/// name = "Mark Gillard"
/// twitter = "https://twitter.com/marzer8789"
///
/// ###### JSON ######
///
/// {
/// "author" : {
/// "github" : "https://github.com/marzer",
/// "name" : "Mark Gillard",
/// "twitter" : "https://twitter.com/marzer8789"
/// },
/// "cpp" : [
/// 17,
/// 20,
/// "and beyond"
/// ],
/// "lib" : "toml++",
/// "repo" : "https://github.com/marzer/tomlplusplus/",
/// "toml" : [
/// "1.0.0-rc.1",
/// "and beyond"
/// ]
/// }
/// \eout
/// \see
/// - toml::default_formatter
/// - toml::json_formatter
///
//////////////////////////////////
///
/// \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
/// 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 \ref TOML_ALL_INLINE to [code]0[/code] 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:
/// \cpp
/// // global_header_that_includes_toml++.h
///
/// #define TOML_ALL_INLINE 0
/// #include <toml.hpp>
/// \ecpp
///
/// <strong>Step 2: Define \ref TOML_IMPLEMENTATION before including toml++ in one specific translation unit</strong>
///
/// \cpp
/// // some_code_file.cpp
///
/// #define TOML_IMPLEMENTATION
/// #include "global_header_that_includes_toml++.h"
/// \ecpp
///
/// <strong>Bonus Step: Disable the parser if you don't need it</strong>
///
/// If all you need to do is serialize some code-generated TOML and don't actually need the parser at all you can
/// set \ref TOML_PARSER to `0` to disable the parser altogether. This can yield fairly significant compilation
/// speedups since the parser accounts for a good chunk of the library's code.
///
///
/// \see \ref configuration
///
//////////////////////////////////////////////////////////////////////
///
/// \section mainpage-adding-lib Adding toml++ to your project
///
/// \m_class{m-note m-default}
///
/// The library comes in two flavours, [emoji icecream] Single-header
/// and [emoji sundae] Regular. The API is the same for both.
///
//////////////////////////////////
///
/// \subsection mainpage-adding-lib-old-school "The old fashioned way"
/// Clone \gh2{marzer/tomlplusplus, the repository} from GitHub, and then:
///
/// <h3>[emoji icecream] Single-header flavour</h3>
/// 1. Drop `toml.hpp` wherever you like in your source tree
/// 2. There is no step two
///
/// <h3>[emoji sundae] Regular flavour</h3>
/// 1. Add `tomlplusplus/include` to your include paths
/// 2. `#include <toml++/toml.h>`
///
//////////////////////////////////
///
/// \subsection mainpage-adding-lib-meson Meson
/// The library supports being added as a subproject in the meson build system.
///
//////////////////////////////////
///
/// \subsection mainpage-adding-lib-conan Conan
/// Add `tomlplusplus/1.3.3` to your conanfile. This adds the single-header version by default, but you can specify the
/// regular version using `multiple_headers": True`.
///
//////////////////////////////////
///
/// \subsection mainpage-adding-lib-vcpkg Vcpkg
/// <em>\gh2{microsoft/vcpkg/pull/10786, coming soon...}</em>
///
//////////////////////////////////
///
/// \subsection mainpage-adding-lib-other Other environments and package managers
/// toml++ is a fairly new project and I'm not up-to-speed with all of the available packaging and integration options
/// in the modern C++ ecosystem. I'm also a cmake novice, for better or worse. If there's an integration option missing
/// be assured that I fully support it being added, and welcome pull requests!
///
//////////////////////////////////
///
/// \subsection mainpage-adding-lib-python Special mention: Python
/// Yes, you read correctly, python. There exists a python wrapper built around toml++ called
/// \gh2{bobfang1992/pytomlpp, pytomlpp}:
///
/// \bash
/// pip install pytomlpp
/// \ebash
///
/// Note that I'm not the developer or maintainer of that project so if you wish to report a bug relating to the python
/// implementation, please do so at their repository, not on the main toml++ one.
///
//////////////////////////////////////////////////////////////////////
///
/// \section mainpage-configuration Library configuration options
/// The library exposes a number of configuration options in the form of compiler `#defines`. Things like
/// changing the `optional<T>` type, using `char8_t` strings, disabling header-only mode, et cetera. The full list of
/// configurables can be found on the \ref configuration page.
///
/// \see \ref configuration
///
//////////////////////////////////////////////////////////////////////
///
/// \section mainpage-contributing Contributing
/// Contributions are very welcome! Either by \gh2{marzer/tomlplusplus/issues, reporting issues}
/// or submitting pull requests. If you wish to submit a pull request,
/// please see \gh2{marzer/tomlplusplus/blob/master/CONTRIBUTING.md, CONTRIBUTING}
/// for all the details you need to get going.
///
//////////////////////////////////////////////////////////////////////
///
/// \section mainpage-license License
///
/// toml++ is licensed under the terms of the MIT license - see
/// [LICENSE](https://github.com/marzer/tomlplusplus/blob/master/LICENSE).
///
/// \m_class{m-note m-default}
///
/// If you're using the single-header version of the library you don't need to explicitly distribute the license file;
/// it is embedded in the preamble at the top of the header.
///
//////////////////////////////////////////////////////////////////////
///
/// \section mainpage-contact Contacting the author
/// For bug reports and feature requests please use the \gh2{marzer/tomlplusplus/issues, Github Issues}
/// system. For anything else you're welcome to reach out via other means. In order of likely response speed:
/// - 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/)
///

9
docs/tomlplusplus.css
View File

@ -17,9 +17,14 @@ header
z-index: 100;
}
article, article > header, article section
article, article > header, article div > section
{
margin-bottom: 3em;
margin-bottom: 5rem;
}
article div > section > section
{
margin-bottom: 1.25rem;
}
pre, code, .tpp-enable-if > a

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

@ -99,427 +99,6 @@
#undef TOML_LAUNDER
#endif
/// \mainpage toml++
///
/// \image html banner_small.png width=1280px
///
/// \tableofcontents
///
///////////////////////////////////////////////////////////////////////
///
/// \section mainpage-features 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 (7+), GCC (7+) and MSVC (VS2019)
/// - Tested on x64, x86 and ARM
///
///////////////////////////////////////////////////////////////////////
///
/// \section mainpage-adding-lib Adding toml++ to your project
/// It's a 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 it's totally
/// optional.
/// \see \ref configuration
///
///////////////////////////////////////////////////////////////////////
///
/// \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.
///
///////////////////////////////////////////////////////////////////////
///
/// \section mainpage-example Basic examples
///
///////////////////////////////////
///
/// \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>
///
/// int main()
/// {
/// toml::table tbl;
/// try
/// {
/// tbl = toml::parse_file("configuration.toml");
/// }
/// catch (const toml::parse_error& err)
/// {
/// std::cerr << "Parsing failed:\n" << err << "\n";
/// return 1;
/// }
///
/// do_stuff_with_your_config(tbl);
///
/// return 0;
/// }
///
/// \ecpp
///
/// \m_class{m-note m-warning}
///
/// \parblock
/// <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::table
/// - toml::parse_error
///
///////////////////////////////////
///
/// \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>
/// #include <toml++/toml.h>
/// using namespace std::string_view_literals;
///
/// int main()
/// {
/// static constexpr std::string_view some_toml = R"(
/// [library]
/// name = "toml++"
/// authors = ["Mark Gillard <mark.gillard@outlook.com.au>"]
/// cpp = 17
/// )"sv;
///
/// 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
/// [library]
/// authors = ["Mark Gillard <mark.gillard@outlook.com.au>"]
/// cpp = 17
/// name = "toml++"
///
/// ... twice
/// \eout
///
/// \see
/// - toml::parse_file()
/// - toml::table
/// - toml::parse_error
///
///////////////////////////////////
///
/// \subsection mainpage-example-parsing-without-exceptions Handling errors without 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
/// Error while parsing key: expected bare key starting character or string delimiter, saw '?'
/// (error occurred at line 2, column 5)
/// \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:
/// \cpp
/// #include <iostream>
/// #include <toml++/toml.h>
/// using namespace std::string_view_literals;
///
/// int main()
/// {
/// static constexpr auto source = R"(
/// numbers = [ 1, 2, 3, "four", 5.0 ]
/// vegetables = [ "tomato", "onion", "mushroom", "lettuce" ]
/// minerals = [ "quartz", "iron", "copper", "diamond" ]
///
/// [animals]
/// cats = [ "tiger", "lion", "puma" ]
/// birds = [ "macaw", "pigeon", "canary" ]
/// fish = [ "salmon", "trout", "carp" ]
///
/// )"sv;
/// auto tbl = toml::parse(source);
///
/// // get a view of the element 'numbers'
/// auto numbers = tbl["numbers"];
/// std::cout << "table has 'numbers': " << !!numbers << "\n";
/// std::cout << "numbers is a: " << numbers.type() << "\n";
/// std::cout << "numbers: " << numbers << "\n";
///
/// // get the underlying array object to do some more advanced stuff
/// if (auto arr = numbers.as_array())
/// {
/// for (auto& elem : *arr)
/// {
/// // visitation helps deal with the polymorphic nature of TOML data
/// elem.visit([](auto&& el) noexcept
/// {
/// if constexpr (toml::is_number<decltype(el)>)
/// (*el)++;
/// else if constexpr (toml::is_string<decltype(el)>)
/// el = "five"sv;
/// });
/// }
///
/// // arrays are very similar to std::vector
/// arr->push_back(7);
/// arr->emplace_back<toml::array>(8, 9);
/// std::cout << "numbers: " << numbers << "\n";
/// }
///
/// // node-views can be chained to quickly query deeper
/// std::cout << "cats: " << tbl["animals"]["cats"] << "\n";
/// std::cout << "fish[1]: " << tbl["animals"]["fish"][1] << "\n";
///
/// // ...even if the element doesn't exist
/// std::cout << "dinosaurs: " << tbl["animals"]["dinosaurs"] << "\n"; //no dinosaurs :(
///
/// return 0;
/// }
/// \ecpp
///
/// \out
/// table has 'numbers': true
/// numbers is an: array
/// numbers: [1, 2, 3, "four", 5.0]
/// numbers: [2, 3, 4, "five", 6.0, 7, [8, 9]]
/// cats: ["tiger", "lion", "puma"]
/// fish[1]: "trout"
/// dinosaurs:
/// \eout
///
/// \see
/// - toml::node
/// - toml::node_view
/// - toml::value
/// - toml::array
/// - toml::table
///
///////////////////////////////////
///
/// \subsection mainpage-example-serialization Serializing as TOML and JSON
/// \cpp
/// #include <iostream>
/// #include <toml++/toml.h>
///
/// int main()
/// {
/// auto tbl = toml::table{{
/// { "lib", "toml++" },
/// { "cpp", toml::array{ 17, 20, "and beyond" } },
/// { "toml", toml::array{ "1.0.0-rc.1", "and beyond" } },
/// { "repo", "https://github.com/marzer/tomlplusplus/" },
/// { "author", toml::table{{
/// { "name", "Mark Gillard" },
/// { "github", "https://github.com/marzer" },
/// { "twitter", "https://twitter.com/marzer8789" }
/// }}
/// },
/// }};
///
/// // serializing as TOML is just writing it to a stream
/// std::cout << "###### TOML ######" << "\n\n";
/// std::cout << tbl << "\n\n";
///
/// // serializing as JSON is _also_ just writing it to a stream, but via a json_formatter:
/// std::cout << "###### JSON ######" << "\n\n";
/// std::cout << toml::json_formatter{ tbl } << "\n\n";
/// return 0;
/// }
/// \ecpp
///
/// \out
/// ###### TOML ######
///
/// cpp = [17, 20, "and beyond"]
/// lib = "toml++"
/// repo = "https://github.com/marzer/tomlplusplus/"
/// toml = ["1.0.0-rc.1", "and beyond"]
///
/// [author]
/// github = "https://github.com/marzer"
/// name = "Mark Gillard"
/// twitter = "https://twitter.com/marzer8789"
///
/// ###### JSON ######
///
/// {
/// "author" : {
/// "github" : "https://github.com/marzer",
/// "name" : "Mark Gillard",
/// "twitter" : "https://twitter.com/marzer8789"
/// },
/// "cpp" : [
/// 17,
/// 20,
/// "and beyond"
/// ],
/// "lib" : "toml++",
/// "repo" : "https://github.com/marzer/tomlplusplus/",
/// "toml" : [
/// "1.0.0-rc.1",
/// "and beyond"
/// ]
/// }
/// \eout
/// \see
/// - toml::default_formatter
/// - toml::json_formatter
///
///////////////////////////////////
///
/// \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
/// 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 \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:
/// \cpp
/// // global_header_that_includes_toml++.h
///
/// #define TOML_ALL_INLINE 0
/// #include <toml.hpp>
/// \ecpp
///
/// <strong>Step 2: Define `TOML_IMPLEMENTATION` before including toml++ in one specific translation unit</strong>
///
/// \cpp
/// // some_code_file.cpp
///
/// #define TOML_IMPLEMENTATION
/// #include "global_header_that_includes_toml++.h"
/// \ecpp
///
/// 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
///
///////////////////////////////////////////////////////////////////////
///
/// \section mainpage-contributing Contributing
/// Contributions are very welcome! Either by [reporting issues](https://github.com/marzer/tomlplusplus/issues)
/// or submitting pull requests. If you wish to submit a pull request,
/// please see [CONTRIBUTING](https://github.com/marzer/tomlplusplus/blob/master/CONTRIBUTING.md)
/// for all the details you need to get going.
///
///////////////////////////////////////////////////////////////////////
///
/// \section mainpage-license License
///
/// toml++ is licensed under the terms of the MIT license - see
/// [LICENSE](https://github.com/marzer/tomlplusplus/blob/master/LICENSE).
///
/// \m_class{m-note m-default}
///
/// If you're using the single-header version of the library you don't need to explicitly distribute the license file;
/// it is embedded in the preamble at the top of the header.
///
///////////////////////////////////////////////////////////////////////
///
/// \section mainpage-contact Contacting the author
/// For bug reports and feature requests please use the [GitHub issues](https://github.com/marzer/tomlplusplus/issues)
/// system. For anything else you're welcome to reach out via other means. In order of likely response speed:
/// - 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/)
///
//# {{
#endif // INCLUDE_TOMLPLUSPLUS_H
//# }}

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

@ -8,10 +8,6 @@
////////// CONFIGURATION
#ifndef TOML_DOXYGEN
#define TOML_DOXYGEN 0
#endif
#ifdef TOML_CONFIG_HEADER
#include TOML_CONFIG_HEADER
#endif
@ -21,11 +17,6 @@
#define TOML_ALL_INLINE 1
#endif
#if TOML_DOXYGEN
#undef TOML_ALL_INLINE
#define TOML_ALL_INLINE 0
#endif
#if defined(TOML_IMPLEMENTATION) || TOML_ALL_INLINE
#undef TOML_IMPLEMENTATION
#define TOML_IMPLEMENTATION 1
@ -62,6 +53,9 @@
#ifndef __cplusplus
#error toml++ is a C++ library.
#endif
#ifndef TOML_DOXYGEN
#define TOML_DOXYGEN 0
#endif
#ifdef __clang__
#define TOML_PUSH_WARNINGS _Pragma("clang diagnostic push")

72
python/generate_documentation.py
View File

@ -15,7 +15,7 @@ import random
import concurrent.futures as futures
import html
import bs4 as soup
import json
inline_namespaces = [
@ -61,6 +61,7 @@ type_names = [
'string_view',
'string',
'byte',
'optional',
#------ toml++ types
'table',
'array',
@ -99,6 +100,12 @@ class HTMLDocument(object):
self.__doc = soup.BeautifulSoup(f, 'html5lib', from_encoding='utf-8')
self.head = self.__doc.head
self.body = self.__doc.body
self.table_of_contents = None
toc_candidates = self.body.main.article.div.div.div('div', class_='m-block m-default', recursive=False)
for div in toc_candidates:
if div.h3 and div.h3.string == 'Contents':
self.table_of_contents = div
break
def flush(self):
with open(self.__path, 'w', encoding='utf-8', newline='\n') as f:
@ -124,14 +131,15 @@ class HTMLDocument(object):
parent.insert(index, tag)
return tag
def find_all_from_sections(self, name=None, select=None, section=None, **kwargs):
def find_all_from_sections(self, name=None, select=None, section=None, include_toc=False, **kwargs):
tags = []
sectionArgs = { }
if (section is not None):
sectionArgs['id'] = section
sections = self.body.main.article.div.div.div('section', recursive=False, **sectionArgs)
if include_toc and self.table_of_contents is not None:
sections = [self.table_of_contents, *sections]
for sect in sections:
matches = sect(name, **kwargs) if name is not None else [ sect ]
if (select is not None):
@ -144,6 +152,7 @@ class HTMLDocument(object):
def html_find_parent(tag, names, cutoff=None):
if not utils.is_collection(names):
names = [ names ]
@ -254,29 +263,72 @@ class RegexReplacer(object):
# allows the injection of custom tags using square-bracketed proxies.
class CustomTagsFix(object):
__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']
__double_tags = re.compile(r"\[\s*(span|div|code|pre|h1|h2|h3|h4|h5|h6)(.*?)\s*\](.*?)\[\s*/\s*\1\s*\]", re.I)
__single_tags = re.compile(r"\[\s*(/?(?:span|div|code|pre|emoji|br|li|ul|ol))(\s.*?)?\s*\]", re.I)
__allowed_parents = ['dd', 'p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'li']
__emojis = None
__emoji_uri = re.compile(r".+unicode/([0-9a-fA-F]+)[.]png.*", re.I)
@classmethod
def __substitute(cls, m):
def __double_tags_substitute(cls, m):
return '<{}{}>{}</{}>'.format(
m.group(1),
html.unescape(m.group(2)),
m.group(3),
m.group(1)
)
@classmethod
def __single_tags_substitute(cls, m):
if (str(m.group(1)).lower() == 'emoji'):
emoji = str(m.group(2)).strip().lower()
if emoji == '':
return ''
if cls.__emojis is None:
cls.__emojis = json.loads(utils.read_all_text_from_file('emojis.json', 'https://api.github.com/emojis'))
if '__processed' not in cls.__emojis:
emojis = {}
for key, uri in cls.__emojis.items():
m2 = cls.__emoji_uri.fullmatch(uri)
if m2:
emojis[key] = [ str(m2.group(1)).upper(), uri ]
aliases = [('sundae', 'ice_cream')]
for alias, key in aliases:
emojis[alias] = emojis[key]
emojis['__processed'] = True
with open('emojis.json', 'w', encoding='utf-8', newline='\n') as f:
f.write(json.dumps(emojis, sort_keys=True, indent=4))
cls.__emojis = emojis
if emoji not in cls.__emojis:
return ''
return '&#x{}'.format(cls.__emojis[emoji][0])
else:
return '<{}{}>'.format(
m.group(1),
(' ' + str(m.group(2)).strip()) if m.group(2) else ''
)
def __call__(self, file, doc):
changed = False
for name in self.__allowedNames:
tags = doc.find_all_from_sections(name)
for name in self.__allowed_parents:
tags = doc.find_all_from_sections(name, include_toc=True)
for tag in tags:
if (len(tag.contents) == 0 or html_find_parent(tag, 'a', doc.body) is not None):
continue
replacer = RegexReplacer(self.__expression, self.__substitute, str(tag))
replacer = RegexReplacer(self.__double_tags, self.__double_tags_substitute, str(tag))
if (replacer):
changed = True
html_replace_tag(tag, str(replacer))
continue
replacer = RegexReplacer(self.__single_tags, self.__single_tags_substitute, str(tag))
if (replacer):
changed = True
html_replace_tag(tag, str(replacer))
continue
return changed

20
python/generate_unicode_functions.py
View File

@ -11,7 +11,6 @@ import os.path as path
import utils
import re
import math
import requests
import bisect
@ -1140,21 +1139,10 @@ def write_to_files(codepoints, header_file, test_file):
def main():
# get unicode character database
codepoint_list = ''
codepoint_file_path = path.join(utils.get_script_folder(), 'UnicodeData.txt')
if (not path.exists(codepoint_file_path)):
print("Couldn't find unicode database file, will download")
response = requests.get(
'https://www.unicode.org/Public/UCD/latest/ucd/UnicodeData.txt',
timeout=1
)
codepoint_list = response.text
with open(codepoint_file_path, 'w', encoding='utf-8', newline='\n') as codepoint_file:
print(codepoint_list, end='', file=codepoint_file)
else:
print("Reading unicode database file into memory")
with open(codepoint_file_path, 'r', encoding='utf-8') as codepoint_file:
codepoint_list = codepoint_file.read()
codepoint_list = utils.read_all_text_from_file(
path.join(utils.get_script_folder(), 'UnicodeData.txt'),
'https://www.unicode.org/Public/UCD/latest/ucd/UnicodeData.txt'
)
# parse the database file into codepoints
re_codepoint = re.compile(r'^([0-9a-fA-F]+);(.+?);([a-zA-Z]+);')

25
python/utils.py
View File

@ -11,6 +11,7 @@ import subprocess
import traceback
import shutil
import fnmatch
import requests
@ -24,11 +25,25 @@ def get_script_folder():
def read_all_text_from_file(path):
print("Reading {}".format(path))
with open(path, 'r', encoding='utf-8') as file:
text = file.read()
return text
def read_all_text_from_file(path, fallback_url=None):
try:
print("Reading {}".format(path))
with open(path, 'r', encoding='utf-8') as f:
text = f.read()
return text
except:
if fallback_url is not None:
print("Couldn't read file locally, downloading from {}...".format(fallback_url))
response = requests.get(
fallback_url,
timeout=1
)
text = response.text
with open(path, 'w', encoding='utf-8', newline='\n') as f:
print(text, end='', file=f)
return text
else:
raise

12
toml.hpp
View File

@ -50,10 +50,6 @@
//-------------- ↓ toml_preprocessor.h -------------------------------------------------------------------------------
#if 1
#ifndef TOML_DOXYGEN
#define TOML_DOXYGEN 0
#endif
#ifdef TOML_CONFIG_HEADER
#include TOML_CONFIG_HEADER
#endif
@ -63,11 +59,6 @@
#define TOML_ALL_INLINE 1
#endif
#if TOML_DOXYGEN
#undef TOML_ALL_INLINE
#define TOML_ALL_INLINE 0
#endif
#if defined(TOML_IMPLEMENTATION) || TOML_ALL_INLINE
#undef TOML_IMPLEMENTATION
#define TOML_IMPLEMENTATION 1
@ -102,6 +93,9 @@
#ifndef __cplusplus
#error toml++ is a C++ library.
#endif
#ifndef TOML_DOXYGEN
#define TOML_DOXYGEN 0
#endif
#ifdef __clang__
#define TOML_PUSH_WARNINGS _Pragma("clang diagnostic push")

3
vs/toml++.vcxproj
View File

@ -87,9 +87,12 @@
</ItemGroup>
<ItemGroup>
<None Include="..\.editorconfig" />
<None Include="..\.gitattributes" />
<None Include="..\.gitignore" />
<None Include="..\CONTRIBUTING.md" />
<None Include="..\docs\Doxyfile" />
<None Include="..\docs\Doxyfile-mcss" />
<None Include="..\docs\main_page.dox" />
<None Include="..\docs\tomlplusplus.css" />
<None Include="..\docs\tomlplusplus.js" />
<None Include="..\meson.build" />

15
vs/toml++.vcxproj.filters
View File

@ -100,16 +100,16 @@
<Filter>python</Filter>
</None>
<None Include="..\docs\Doxyfile">
<Filter>doc</Filter>
<Filter>docs</Filter>
</None>
<None Include="..\docs\Doxyfile-mcss">
<Filter>doc</Filter>
<Filter>docs</Filter>
</None>
<None Include="..\docs\tomlplusplus.css">
<Filter>doc</Filter>
<Filter>docs</Filter>
</None>
<None Include="..\docs\tomlplusplus.js">
<Filter>doc</Filter>
<Filter>docs</Filter>
</None>
<None Include="..\CONTRIBUTING.md" />
<None Include="..\meson.build" />
@ -120,6 +120,11 @@
<None Include="..\python\generate_conformance_tests.py">
<Filter>python</Filter>
</None>
<None Include="..\docs\main_page.dox">
<Filter>docs</Filter>
</None>
<None Include="..\.gitattributes" />
<None Include="..\.gitignore" />
</ItemGroup>
<ItemGroup>
<Filter Include="include">
@ -128,7 +133,7 @@
<Filter Include="python">
<UniqueIdentifier>{5ba46476-31a3-484e-aee7-f840dd2202b1}</UniqueIdentifier>
</Filter>
<Filter Include="doc">
<Filter Include="docs">
<UniqueIdentifier>{5ed0949f-6855-4664-ad86-2b38ceeb400b}</UniqueIdentifier>
</Filter>
</ItemGroup>