diff --git a/index.html b/index.html index ce069c9..52d6dd5 100644 --- a/index.html +++ b/index.html @@ -100,57 +100,60 @@

Features

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.

Basic examples

Parsing files

Call toml::parse_file() and work with the toml::table you get back, or handle any toml::parse_error that gets thrown:

#include <iostream>
 #include <toml++/toml.hpp>
 
-int main(int argc, char** argv)
+int main(int argc, char\*\* argv)
 {
-    toml::table tbl;
-    try
-    {
-        tbl = toml::parse_file(argv[1]);
-            std::cout << tbl << "\n";
-    }
-    catch (const toml::parse_error& err)
-    {
-        std::cerr << "Parsing failed:\n" << err << "\n";
-        return 1;
-    }
+toml::table tbl;
+try
+{
+tbl = toml::parse_file(argv[1]);
+std::cout << tbl << "\n";
+}
+catch (const toml::parse_error& err)
+{
+std::cerr << "Parsing failed:\n" << err << "\n";
+return 1;
+}
 
     return 0;
-}

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:

Try this code on Compiler Explorer
#include <iostream>
+
+}

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:

Try this code on Compiler Explorer
#include <iostream>
 #include <sstream>
 #include <toml++/toml.hpp>
 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;
+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;
-    }
+// 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;
+
 }
[library]
 authors = [ 'Mark Gillard <mark.gillard@outlook.com.au>' ]
 cpp = 17
@@ -159,52 +162,53 @@
 [library]
 authors = [ 'Mark Gillard <mark.gillard@outlook.com.au>' ]
 cpp = 17
-name = 'toml++'

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 TOML_EXCEPTIONS to 0. In either case, the parsing functions return a toml::parse_result instead of a toml::table:

#include <iostream>
+name = 'toml++'

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 TOML_EXCEPTIONS to 0. In either case, the parsing functions return a toml::parse_result instead of a toml::table:

#include <iostream>
 
 #define TOML_EXCEPTIONS 0 // only necessary if you've left them enabled in your compiler
 #include <toml++/toml.hpp>
 
 int main()
 {
-    toml::parse_result result = toml::parse_file("configuration.toml");
-    if (!result)
-    {
-        std::cerr << "Parsing failed:\n" << result.error() << "\n";
-        return 1;
-    }
+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(std::move(result).table()); // 'steal' the table from the result
     return 0;
+
 }

Custom error formatting

The examples above use an overloaded operator<< with ostreams to print basic error messages, and look like this:

Error while parsing key: expected bare key starting character or string delimiter, saw '?'
-    (error occurred at line 2, column 5)

The library doesn't natively support error colouring in TTY environments, but instead provides the requisite information for you to build that and any other custom error handling yourself if necessary via toml::parse_error's source() and description() members:

toml::table tbl;
+(error occurred at line 2, column 5)

The library doesn't natively support error colouring in TTY environments, but instead provides the requisite information for you to build that and any other custom error handling yourself if necessary via toml::parse_error's source() and description() members:

toml::table tbl;
 try
 {
-    tbl = toml::parse_file("configuration.toml");
+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;
-}

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:

Try this code on Compiler Explorer
#include <iostream>
+std::cerr
+<< "Error parsing file '" << \*err.source().path
+<< "':\n" << err.description()
+<< "\n (" << err.source().begin << ")\n";
+return 1;
+}

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:

Try this code on Compiler Explorer
#include <iostream>
 #include <toml++/toml.hpp>
 using namespace std::string_view_literals;
 
 int main()
 {
-    static constexpr auto source = R"(
-        str = "hello world"
+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" ]
+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" ]
+[animals]
+cats = [ "tiger", "lion", "puma" ]
+birds = [ "macaw", "pigeon", "canary" ]
+fish = [ "salmon", "trout", "carp" ]
 
     )"sv;
     toml::table tbl = toml::parse(source);
@@ -238,11 +242,11 @@
                 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";
-    }
+// 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";
@@ -256,6 +260,7 @@
     std::cout << "dinosaurs: " << tbl["animals"]["dinosaurs"] << "\n"; //no dinosaurs :(
 
     return 0;
+
 }
hello world
 hello world
 hello world
@@ -266,23 +271,23 @@
 numbers: [ 2, 3, 4, 'five', 6.0, 7, [ 8, 9 ] ]
 cats: [ 'tiger', 'lion', 'puma' ]
 fish[1]: 'trout'
-dinosaurs:

Serializing as TOML, JSON and YAML

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 and YAML is done in much the same way, but via a toml::json_formatter and toml::yaml_formatter.

Try this code on Compiler Explorer
#include <iostream>
+dinosaurs:

Serializing as TOML, JSON and YAML

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 and YAML is done in much the same way, but via a toml::json_formatter and toml::yaml_formatter.

Try this code on Compiler Explorer
#include <iostream>
 #include <toml++/toml.hpp>
 
 int main()
 {
-    auto tbl = toml::table{
-        { "lib", "toml++" },
-        { "cpp", toml::array{ 17, 20, "and beyond" } },
-        { "toml", toml::array{ "1.0.0", "and beyond" } },
-        { "repo", "https://github.com/marzer/tomlplusplus/" },
-        { "author", toml::table{
-                { "name", "Mark Gillard" },
-                { "github", "https://github.com/marzer" },
-                { "twitter", "https://twitter.com/marzer8789" }
-            }
-        },
-    };
+auto tbl = toml::table{
+{ "lib", "toml++" },
+{ "cpp", toml::array{ 17, 20, "and beyond" } },
+{ "toml", toml::array{ "1.0.0", "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";
@@ -297,7 +302,8 @@
     std::cout << toml::yaml_formatter{ tbl } << "\n\n";
 
     return 0;
-}
###### TOML ######
+
+}
###### TOML
 
 cpp = [ 17, 20, 'and beyond' ]
 lib = 'toml++'
@@ -309,64 +315,65 @@
 name = 'Mark Gillard'
 twitter = 'https://twitter.com/marzer8789'
 
-###### JSON ######
+###### 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",
-        "and beyond"
-    ]
+"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",
+"and beyond"
+]
 }
 
-###### YAML ######
+###### YAML
 
 author:
-  github: 'https://github.com/marzer'
-  name: 'Mark Gillard'
-  twitter: 'https://twitter.com/marzer8789'
+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'
-  - 'and beyond'

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 header-only mode and explicitly controlling where the library's implementation is compiled.

Step 1: Set TOML_HEADER_ONLY to 0 before including toml++

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:

// global_header_that_includes_toml++.h
+
+-   17
+-   20
+-   'and beyond'
+    lib: 'toml++'
+    repo: 'https://github.com/marzer/tomlplusplus/'
+    toml:
+-   '1.0.0'
+-   'and beyond'

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 header-only mode and explicitly controlling where the library's implementation is compiled.

Step 1: Set TOML_HEADER_ONLY to 0 before including toml++

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:

// global_header_that_includes_toml++.h
 
 #define TOML_HEADER_ONLY 0
 #include <toml.hpp>

Step 2: Define TOML_IMPLEMENTATION before including toml++ in one specific translation unit

// some_code_file.cpp
 
 #define TOML_IMPLEMENTATION
-#include "global_header_that_includes_toml++.h"

Bonus Step: Disable any library features you don't need

Some library features can be disabled wholesale so you can avoid paying their the compilation cost if you don't need them. For example, if all you need to do is serialize some code-generated TOML and don't actually need the parser at all you, can set TOML_ENABLE_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.

Adding toml++ to your project

"The old fashioned way"

The library comes in two flavours, 🍦️ Single-header and 🍨️ Regular. The API is the same for both.

🍦️ Single-header flavour

  1. Drop toml.hpp wherever you like in your source tree
  2. There is no step two

🍨️ Regular flavour

  1. Clone the repository from GitHub
  2. Add tomlplusplus/include to your include paths
  3. #include <toml++/toml.hpp>

Conan

Add tomlplusplus/3.3.0 to your conanfile.

DDS

Add tomlpp to your package.json5, e.g.:

depends: [
-    'tomlpp^3.3.0',
+#include "global_header_that_includes_toml++.hpp"

Bonus Step: Disable any library features you don't need

Some library features can be disabled wholesale so you can avoid paying their the compilation cost if you don't need them. For example, if all you need to do is serialize some code-generated TOML and don't actually need the parser at all you, can set TOML_ENABLE_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.

Adding toml++ to your project

"The old fashioned way"

The library comes in two flavours, 🍦️ Single-header and 🍨️ Regular. The API is the same for both.

🍦️ Single-header flavour

  1. Drop toml.hpp wherever you like in your source tree
  2. There is no step two

🍨️ Regular flavour

  1. Clone the repository from GitHub
  2. Add tomlplusplus/include to your include paths
  3. #include <toml++/toml.hpp>

Conan

Add tomlplusplus/3.4.0 to your conanfile.

DDS

Add tomlpp to your package.json5, e.g.:

depends: [
+'tomlpp^3.4.0',
 ]

Meson

You can install the wrap with:

meson wrap install tomlplusplus

After that, you can use it like a regular dependency:

tomlplusplus_dep = dependency('tomlplusplus')

You can also add it as a subproject directly.

Tipi.build

tomlplusplus can be easily used in tipi.build projects by adding the following entry to your .tipi/deps:

{
-    "marzer/tomlplusplus": { }
+"marzer/tomlplusplus": { }
 }

Vcpkg

vcpkg install tomlplusplus

CMake FetchContent

include(FetchContent)
 FetchContent_Declare(
-    tomlplusplus
-    GIT_REPOSITORY https://github.com/marzer/tomlplusplus.git
-    GIT_TAG        v3.3.0
+tomlplusplus
+GIT_REPOSITORY https://github.com/marzer/tomlplusplus.git
+GIT_TAG v3.4.0
 )
 FetchContent_MakeAvailable(tomlplusplus)

Git submodules

git submodule add --depth 1 https://github.com/marzer/tomlplusplus.git tomlplusplus

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.

Special mention: Python

There exists a python wrapper library built around toml++ called pytomlpp which is, at the time of writing, one of only two natively-compiled TOML libraries available for python, and thus one of the fastest options available:

Parsing data.toml 5000 times:
-    pytomlpp:  0.694 s
-    rtoml:     0.871 s ( 1.25x)
-    tomli:     2.625 s ( 3.78x)
-    toml:      5.642 s ( 8.12x)
-    qtoml:     7.760 s (11.17x)
-    tomlkit:  32.708 s (47.09x)

Install it using pip:

pip install pytomlpp

Note that I'm not the owner 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.

Library configuration options

The library exposes a number of configuration options in the form of compiler #defines. Things like changing the optional<T> type, disabling header-only mode, et cetera. The full list of configurables can be found on the Library Configuration page.

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.

License

toml++ is licensed under the terms of the MIT license - see LICENSE.

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.

Contacting the author

For bug reports and feature requests please use the Github Issues system. For anything else you're welcome to reach out via other means. In order of likely response speed:

+pytomlpp: 0.694 s +rtoml: 0.871 s ( 1.25x) +tomli: 2.625 s ( 3.78x) +toml: 5.642 s ( 8.12x) +qtoml: 7.760 s (11.17x) +tomlkit: 32.708 s (47.09x)

Install it using pip:

pip install pytomlpp

Note that I'm not the owner 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.

Library configuration options

The library exposes a number of configuration options in the form of compiler #defines. Things like changing the optional<T> type, disabling header-only mode, et cetera. The full list of configurables can be found on the Library Configuration page.

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.

License

toml++ is licensed under the terms of the MIT license - see LICENSE.

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.

Contacting the author

For bug reports and feature requests please use the Github Issues system. For anything else you're welcome to reach out via other means. In order of likely response speed:

diff --git a/poxy_changelog.html b/poxy_changelog.html index e6ed658..0bf0b52 100644 --- a/poxy_changelog.html +++ b/poxy_changelog.html @@ -64,7 +64,7 @@ -

Unreleased

Fixes
Additions
Changes:
Build system:

v3.3.0

Released 2023-01-29

Fixes:
Additions:
Removals:
Build system:

v3.2.0

Released 2022-08-29

Fixes:
Additions:
Changes:

v3.1.0

Released 2022-04-22

Fixes:
Additions:
Removals/Deprecations:
Build system:

v3.0.1

Released 2022-01-13

This is a single-bugfix release to fix an ODR issue for people using header-only mode in multiple translation units. If you aren't seeing linker errors because of toml::array::insert_at(), this release holds nothing of value over v3.0.0.

Fixes:

v3.0.0

Released 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 ⚠️.

Fixes:
Additions:
Changes:
Removals:
Build system:

v2.5.0

Released 2021-07-11

Fixes:
Additions:
Changes:

v2.4.0

Released 2021-05-19

Fixes:
Additions:
Removals:

v2.3.0

Released 2020-12-29

Fixes:

v2.2.0

Released 2020-08-09

Fixes:
Additions:
Changes:
Build system:

v2.1.0

Released 2020-07-11

Fixes:
Additions:
Changes:

v2.0.0

Released 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 ⚠️.

Fixes:
Additions:
Changes:
Removals:

v1.3.3

Released 2020-06-29

Fixes:
Additions:
Changes:

v1.3.2

Released 2020-06-19

Fixes:
Changes:

v1.3.0

Released 2020-06-02

Fixes:
Additions:
Changes:

v1.2.5

Released 2020-04-24

Fixes:
Additions:
Changes:

v1.2.3

Released 2020-04-11

Fixes:
Additions:
Changes:

v1.2.0

Released 2020-04-07

Fixes:
Additions:

v1.1.0

Released 2020-04-03

Fixes:
Additions:

v1.0.0

Released 2020-03-28

Fixes:
Changes:

v0.6.0

Released 2020-03-24

Fixes:
Additions:

v0.5.0

Released 2020-03-18

Fixes:
Additions:

v0.4.3

Released 2020-03-10

Fixes:
Additions:
Changes:

v0.4.0

Released 2020-03-05

Fixes:
Additions:

v0.3.0

Released 2020-03-01

Fixes:
Additions:
Removals:

v0.2.1

Released 2020-02-26

Fixes:
Additions:
Changes:

v0.2.0

Released 2020-02-23

Fixes:
Additions:

v0.1.0

Released 2020-02-20

+

v3.4.0

Fixes
Additions
Changes:
Build system:

v3.3.0

Released 2023-01-29

Fixes:
Additions:
Removals:
Build system:

v3.2.0

Released 2022-08-29

Fixes:
Additions:
Changes:

v3.1.0

Released 2022-04-22

Fixes:
Additions:
Removals/Deprecations:
Build system:

v3.0.1

Released 2022-01-13

This is a single-bugfix release to fix an ODR issue for people using header-only mode in multiple translation units. If you aren't seeing linker errors because of toml::array::insert_at(), this release holds nothing of value over v3.0.0.

Fixes:

v3.0.0

Released 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 ⚠️.

Fixes:
Additions:
Changes:
Removals:
Build system:

v2.5.0

Released 2021-07-11

Fixes:
Additions:
Changes:

v2.4.0

Released 2021-05-19

Fixes:
Additions:
Removals:

v2.3.0

Released 2020-12-29

Fixes:

v2.2.0

Released 2020-08-09

Fixes:
Additions:
Changes:
Build system:

v2.1.0

Released 2020-07-11

Fixes:
Additions:
Changes:

v2.0.0

Released 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 ⚠️.

Fixes:
Additions:
Changes:
Removals:

v1.3.3

Released 2020-06-29

Fixes:
Additions:
Changes:

v1.3.2

Released 2020-06-19

Fixes:
Changes:

v1.3.0

Released 2020-06-02

Fixes:
Additions:
Changes:

v1.2.5

Released 2020-04-24

Fixes:
Additions:
Changes:

v1.2.3

Released 2020-04-11

Fixes:
Additions:
Changes:

v1.2.0

Released 2020-04-07

Fixes:
Additions:

v1.1.0

Released 2020-04-03

Fixes:
Additions:

v1.0.0

Released 2020-03-28

Fixes:
Changes:

v0.6.0

Released 2020-03-24

Fixes:
Additions:

v0.5.0

Released 2020-03-18

Fixes:
Additions:

v0.4.3

Released 2020-03-10

Fixes:
Additions:
Changes:

v0.4.0

Released 2020-03-05

Fixes:
Additions:

v0.3.0

Released 2020-03-01

Fixes:
Additions:
Removals:

v0.2.1

Released 2020-02-26

Fixes:
Additions:
Changes:

v0.2.0

Released 2020-02-23

Fixes:
Additions:

v0.1.0

Released 2020-02-20