mirror of
https://github.com/ToruNiina/toml11.git
synced 2025-09-17 09:08:08 +08:00
Merge pull request #291 from franzpoeschel/namespace-versioning
Use an inline namespace to distinguish emitted symbols by version numbers e4051f77d7
This commit is contained in:
ToruNiina
146
docs/features/configure_types/index.html
Normal file
146
docs/features/configure_types/index.html
Normal file
@@ -0,0 +1,146 @@
|
||||
<!doctype html><html lang=en dir=ltr><head><meta charset=UTF-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="
|
||||
Customizing Types
|
||||
#
|
||||
|
||||
The toml::value class uses std::int64_t for integer_type and std::unordered_map<key_type, value_type> for table_type.
|
||||
However, in some cases, you may want to use boost::multiprecision::int128_t or std::map.
|
||||
To accommodate this, toml::value is implemented with template parameters that allow you to change the stored types.
|
||||
Just as std::string is actually an alias for std::basic_string<char, std::char_traits<char>, std::allocator<char>>, toml::value is an alias for toml::basic_value<toml::type_config>.
|
||||
Here, we will explain the types contained in toml::type_config and how to define a different config type."><meta name=theme-color media="(prefers-color-scheme: light)" content="#ffffff"><meta name=theme-color media="(prefers-color-scheme: dark)" content="#343a40"><meta name=color-scheme content="light dark"><meta property="og:url" content="https://toruniina.github.io/toml11/docs/features/configure_types/"><meta property="og:site_name" content="toml11"><meta property="og:title" content="configuring types"><meta property="og:description" content="Customizing Types # The toml::value class uses std::int64_t for integer_type and std::unordered_map<key_type, value_type> for table_type.
|
||||
However, in some cases, you may want to use boost::multiprecision::int128_t or std::map.
|
||||
To accommodate this, toml::value is implemented with template parameters that allow you to change the stored types.
|
||||
Just as std::string is actually an alias for std::basic_string<char, std::char_traits<char>, std::allocator<char>>, toml::value is an alias for toml::basic_value<toml::type_config>.
|
||||
Here, we will explain the types contained in toml::type_config and how to define a different config type."><meta property="og:locale" content="en"><meta property="og:type" content="article"><meta property="article:section" content="docs"><title>configuring types | toml11</title>
|
||||
<link rel=manifest href=/toml11/manifest.json><link rel=icon href=/toml11/favicon.png><link rel=canonical href=https://toruniina.github.io/toml11/docs/features/configure_types/><link rel=alternate hreflang=ja href=https://toruniina.github.io/toml11/ja/docs/features/configure_types/ title="configuring types"><link rel=stylesheet href=/toml11/book.min.ddac3efe7ea4c1007ff53e5a8fd67f12517e5d2e99984d8c67a18668f7ecaa03.css integrity="sha256-3aw+/n6kwQB/9T5aj9Z/ElF+XS6ZmE2MZ6GGaPfsqgM=" crossorigin=anonymous><script defer src=/toml11/fuse.min.js></script><script defer src=/toml11/en.search.min.db4a558804ac41f081539588cec8e4a415587801da466728166bb5341dd62411.js integrity="sha256-20pViASsQfCBU5WIzsjkpBVYeAHaRmcoFmu1NB3WJBE=" crossorigin=anonymous></script></head><body dir=ltr><input type=checkbox class="hidden toggle" id=menu-control>
|
||||
<input type=checkbox class="hidden toggle" id=toc-control><main class="container flex"><aside class=book-menu><div class=book-menu-content><nav><h2 class=book-brand><a class="flex align-center" href=/toml11/><span>toml11</span></a></h2><div class="book-search hidden"><input type=text id=book-search-input placeholder=Search aria-label=Search maxlength=64 data-hotkeys=s/><div class="book-search-spinner hidden"></div><ul id=book-search-results></ul></div><script>document.querySelector(".book-search").classList.remove("hidden")</script><ul class=book-languages><li><input type=checkbox id=languages class=toggle>
|
||||
<label for=languages class="flex justify-between"><a role=button class="flex align-center"><img src=/toml11/svg/translate.svg class=book-icon alt=Languages>
|
||||
English</a></label><ul><li><a href=https://toruniina.github.io/toml11/ja/docs/features/configure_types/>日本語</a></li></ul></li></ul><ul><li><a href=/toml11/docs/installation/>installation</a><ul></ul></li><li><input type=checkbox id=section-291123c850af98d8b815ccdbb4c33657 class=toggle checked>
|
||||
<label for=section-291123c850af98d8b815ccdbb4c33657 class="flex justify-between"><a href=/toml11/docs/features/>features</a></label><ul><li><a href=/toml11/docs/features/parsing_files/>parsing files</a></li><li><a href=/toml11/docs/features/value/>getting values</a></li><li><a href=/toml11/docs/features/error_message/>error message</a></li><li><a href=/toml11/docs/features/serialize/>serializing values</a></li><li><a href=/toml11/docs/features/configure_types/ class=active>configuring types</a></li><li><a href=/toml11/docs/features/literal/>toml literal</a></li><li><a href=/toml11/docs/features/toml_spec/>toml spec</a></li><li><a href=/toml11/docs/features/extension/>extension</a></li></ul></li><li><input type=checkbox id=section-e2e812e55021b82e114feaae98f1a02e class=toggle>
|
||||
<label for=section-e2e812e55021b82e114feaae98f1a02e class="flex justify-between"><a href=/toml11/docs/reference/>reference</a></label><ul><li><a href=/toml11/docs/reference/color/>color.hpp</a></li><li><a href=/toml11/docs/reference/comments/>comments.hpp</a></li><li><a href=/toml11/docs/reference/conversion/>conversion.hpp</a></li><li><a href=/toml11/docs/reference/datetime/>datetime.hpp</a></li><li><a href=/toml11/docs/reference/error_info/>error_info.hpp</a></li><li><a href=/toml11/docs/reference/exception/>exception.hpp</a></li><li><a href=/toml11/docs/reference/find/>find.hpp</a></li><li><a href=/toml11/docs/reference/format/>format.hpp</a></li><li><a href=/toml11/docs/reference/from/>from.hpp</a></li><li><a href=/toml11/docs/reference/get/>get.hpp</a></li><li><a href=/toml11/docs/reference/into/>into.hpp</a></li><li><a href=/toml11/docs/reference/literal/>literal.hpp</a></li><li><a href=/toml11/docs/reference/ordered_map/>ordered_map.hpp</a></li><li><a href=/toml11/docs/reference/parser/>parser.hpp</a></li><li><a href=/toml11/docs/reference/result/>result.hpp</a></li><li><a href=/toml11/docs/reference/serializer/>serializer.hpp</a></li><li><a href=/toml11/docs/reference/source_location/>source_location.hpp</a></li><li><a href=/toml11/docs/reference/spec/>spec.hpp</a></li><li><a href=/toml11/docs/reference/toml_fwd/>toml_fwd.hpp</a></li><li><a href=/toml11/docs/reference/toml/>toml.hpp</a></li><li><a href=/toml11/docs/reference/types/>types.hpp</a></li><li><a href=/toml11/docs/reference/value_t/>value_t.hpp</a></li><li><a href=/toml11/docs/reference/value/>value.hpp</a></li><li><a href=/toml11/docs/reference/version/>version.hpp</a></li><li><a href=/toml11/docs/reference/visit/>visit.hpp</a></li></ul></li><li><a href=/toml11/docs/changelog/>changelog</a><ul></ul></li></ul><ul><li><a href=https://github.com/ToruNiina/toml11 target=_blank rel=noopener>GitHub</a></li></ul></nav><script>(function(){var e=document.querySelector("aside .book-menu-content");addEventListener("beforeunload",function(){localStorage.setItem("menu.scrollTop",e.scrollTop)}),e.scrollTop=localStorage.getItem("menu.scrollTop")})()</script></div></aside><div class=book-page><header class=book-header><div class="flex align-center justify-between"><label for=menu-control><img src=/toml11/svg/menu.svg class=book-icon alt=Menu>
|
||||
</label><strong>configuring types</strong>
|
||||
<label for=toc-control><img src=/toml11/svg/toc.svg class=book-icon alt="Table of Contents"></label></div><aside class="hidden clearfix"><nav id=TableOfContents><ul><li><a href=#customizing-types>Customizing Types</a><ul><li><a href=#type_config><code>type_config</code></a></li><li><a href=#preserving-order-of-values-in-tables>Preserving Order of Values in Tables</a></li><li><a href=#not-preserving-comments>Not Preserving Comments</a></li><li><a href=#using-containers-other-than-stdvector-for-arrays>Using Containers Other Than <code>std::vector</code> for Arrays</a></li><li><a href=#using-boostmultiprecision-for-numeric-types>Using <code>boost::multiprecision</code> for Numeric Types</a></li></ul></li></ul></nav></aside></header><article class="markdown book-article"><h1 id=customizing-types>Customizing Types
|
||||
<a class=anchor href=#customizing-types>#</a></h1><p>The <code>toml::value</code> class uses <code>std::int64_t</code> for <code>integer_type</code> and <code>std::unordered_map<key_type, value_type></code> for <code>table_type</code>.</p><p>However, in some cases, you may want to use <code>boost::multiprecision::int128_t</code> or <code>std::map</code>.</p><p>To accommodate this, <code>toml::value</code> is implemented with template parameters that allow you to change the stored types.</p><p>Just as <code>std::string</code> is actually an alias for <code>std::basic_string<char, std::char_traits<char>, std::allocator<char>></code>, <code>toml::value</code> is an alias for <code>toml::basic_value<toml::type_config></code>.</p><p>Here, we will explain the types contained in <code>toml::type_config</code> and how to define a different <code>config</code> type.</p><h2 id=type_config><code>type_config</code>
|
||||
<a class=anchor href=#type_config>#</a></h2><p>The <code>type_config</code> class contains the following member types and <code>static</code> member functions:</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>namespace</span> toml
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>struct</span> <span style=color:#a6e22e>type_config</span>
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> comment_type <span style=color:#f92672>=</span> preserve_comments;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> boolean_type <span style=color:#f92672>=</span> <span style=color:#66d9ef>bool</span>;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> integer_type <span style=color:#f92672>=</span> std<span style=color:#f92672>::</span><span style=color:#66d9ef>int64_t</span>;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> floating_type <span style=color:#f92672>=</span> <span style=color:#66d9ef>double</span>;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> string_type <span style=color:#f92672>=</span> std<span style=color:#f92672>::</span>string;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>template</span><span style=color:#f92672><</span><span style=color:#66d9ef>typename</span> T<span style=color:#f92672>></span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> array_type <span style=color:#f92672>=</span> std<span style=color:#f92672>::</span>vector<span style=color:#f92672><</span>T<span style=color:#f92672>></span>;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>template</span><span style=color:#f92672><</span><span style=color:#66d9ef>typename</span> K, <span style=color:#66d9ef>typename</span> T<span style=color:#f92672>></span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> table_type <span style=color:#f92672>=</span> std<span style=color:#f92672>::</span>unordered_map<span style=color:#f92672><</span>K, T<span style=color:#f92672>></span>;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>static</span> result<span style=color:#f92672><</span>integer_type, error_info<span style=color:#f92672>></span>
|
||||
</span></span><span style=display:flex><span> parse_int(<span style=color:#66d9ef>const</span> std<span style=color:#f92672>::</span>string<span style=color:#f92672>&</span> str, <span style=color:#66d9ef>const</span> source_location src, <span style=color:#66d9ef>const</span> std<span style=color:#f92672>::</span><span style=color:#66d9ef>uint8_t</span> base);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>static</span> result<span style=color:#f92672><</span>floating_type, error_info<span style=color:#f92672>></span>
|
||||
</span></span><span style=display:flex><span> parse_float(<span style=color:#66d9ef>const</span> std<span style=color:#f92672>::</span>string<span style=color:#f92672>&</span> str, <span style=color:#66d9ef>const</span> source_location src, <span style=color:#66d9ef>const</span> <span style=color:#66d9ef>bool</span> is_hex);
|
||||
</span></span><span style=display:flex><span>};
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><p><code>toml::basic_value<TypeConfig></code> defines the stored <code>boolean_type</code> as <code>TypeConfig::boolean_type</code>, the stored <code>integer_type</code> as <code>TypeConfig::integer_type</code>, and so on.</p><p>Additionally, <code>array_type</code> is defined as <code>TypeConfig::array_type<toml::basic_value<TypeConfig>></code> and <code>table_type</code> is defined as <code>TypeConfig::table_type<key_type, toml::basic_value<TypeConfig>></code>.</p><p>By passing a class that defines these member types and functions to <code>toml::basic_value</code>, you can customize the types used by that <code>toml::basic_value</code>.</p><p>The <code>parse_int</code> and <code>parse_float</code> functions provide parsing methods when custom numeric types are used. These functions receive strings with prefixes like <code>0x</code> and digit separators like <code>_</code> removed, such as <code>123456</code> or <code>DEADBEEF</code>. The <code>base</code> parameter will be one of <code>10</code>, <code>16</code>, <code>8</code>, or <code>2</code>. Implement these functions to parse your custom <code>integer_type</code> and <code>floating_type</code>.</p><p>As a default implementation, <code>toml::read_int</code> and <code>toml::read_float</code> are provided.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>static</span> result<span style=color:#f92672><</span>integer_type, error_info<span style=color:#f92672>></span>
|
||||
</span></span><span style=display:flex><span>parse_int(<span style=color:#66d9ef>const</span> std<span style=color:#f92672>::</span>string<span style=color:#f92672>&</span> str, <span style=color:#66d9ef>const</span> source_location src, <span style=color:#66d9ef>const</span> std<span style=color:#f92672>::</span><span style=color:#66d9ef>uint8_t</span> base)
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> toml<span style=color:#f92672>::</span>read_int<span style=color:#f92672><</span>integer_type<span style=color:#f92672>></span>(str, src, base);
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>static</span> result<span style=color:#f92672><</span>floating_type, error_info<span style=color:#f92672>></span>
|
||||
</span></span><span style=display:flex><span>parse_float(<span style=color:#66d9ef>const</span> std<span style=color:#f92672>::</span>string<span style=color:#f92672>&</span> str, <span style=color:#66d9ef>const</span> source_location src, <span style=color:#66d9ef>const</span> <span style=color:#66d9ef>bool</span> is_hex)
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> toml<span style=color:#f92672>::</span>read_float<span style=color:#f92672><</span>floating_type<span style=color:#f92672>></span>(str, src, is_hex);
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><p>The <code>read_int</code> function uses <code>istream</code> and employs <code>std::hex</code> and <code>std::oct</code> for hexadecimal and octal parsing, respectively. For binary parsing, it is implemented using multiplication and addition. If your type supports these operations, you can use <code>read_int</code> as-is.</p><p>The <code>read_float</code> function also uses <code>istream</code>. Hexadecimal floating-point numbers are only supported for <code>double</code> and <code>float</code> types. If <code>read_float</code> is called with any other type and <code>hexfloat</code> is used, it will always return a parse error. Therefore, if you need to use a floating-point type other than <code>double</code> or <code>float</code> with <code>hexfloat</code>, you will need to implement support for that. If <code>hexfloat</code> is not used, no additional implementation is necessary.</p><h2 id=preserving-order-of-values-in-tables>Preserving Order of Values in Tables
|
||||
<a class=anchor href=#preserving-order-of-values-in-tables>#</a></h2><p>In addition to the default <code>toml::type_config</code>, there is also <code>toml::ordered_type_config</code>. This changes the <code>table_type</code> to an <a href=https://toruniina.github.io/toml11/docs/reference/ordered_map/>ordered_map</a>.</p><p>Using this, <code>toml::ordered_value</code> is defined, along with aliases for its array and table types as <code>toml::ordered_array</code> and <code>toml::ordered_table</code>, respectively.</p><p>You can use <code>toml::ordered_value</code> by calling <code>toml::parse(...)</code> as <code>toml::parse<toml::ordered_type_config>(...)</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><toml.hpp></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>int</span> <span style=color:#a6e22e>main</span>()
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> toml<span style=color:#f92672>::</span>ordered_value input <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse<span style=color:#f92672><</span>toml<span style=color:#f92672>::</span>ordered_type_config<span style=color:#f92672>></span>(<span style=color:#e6db74>"example.toml"</span>);
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> toml<span style=color:#f92672>::</span>format(input) <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> <span style=color:#ae81ff>0</span>;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><h2 id=not-preserving-comments>Not Preserving Comments
|
||||
<a class=anchor href=#not-preserving-comments>#</a></h2><p>The <code>type_config</code> defines a container for storing comments via <code>comment_type</code>.</p><p>If comments do not contain significant information and can be discarded during parsing, specify <code>toml::discard_comments</code> for <code>comment_type</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>struct</span> <span style=color:#a6e22e>wo_comment_config</span>
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> comment_type <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>discard_comments; <span style=color:#75715e>// XXX
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> boolean_type <span style=color:#f92672>=</span> <span style=color:#66d9ef>bool</span>;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> integer_type <span style=color:#f92672>=</span> std<span style=color:#f92672>::</span><span style=color:#66d9ef>int64_t</span>;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> floating_type <span style=color:#f92672>=</span> <span style=color:#66d9ef>double</span>;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> string_type <span style=color:#f92672>=</span> std<span style=color:#f92672>::</span>string;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>template</span><span style=color:#f92672><</span><span style=color:#66d9ef>typename</span> T<span style=color:#f92672>></span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> array_type <span style=color:#f92672>=</span> std<span style=color:#f92672>::</span>vector<span style=color:#f92672><</span>T<span style=color:#f92672>></span>;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>template</span><span style=color:#f92672><</span><span style=color:#66d9ef>typename</span> K, <span style=color:#66d9ef>typename</span> T<span style=color:#f92672>></span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> table_type <span style=color:#f92672>=</span> std<span style=color:#f92672>::</span>unordered_map<span style=color:#f92672><</span>K, T<span style=color:#f92672>></span>;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>static</span> result<span style=color:#f92672><</span>integer_type, error_info<span style=color:#f92672>></span>
|
||||
</span></span><span style=display:flex><span> parse_int(<span style=color:#66d9ef>const</span> std<span style=color:#f92672>::</span>string<span style=color:#f92672>&</span> str, <span style=color:#66d9ef>const</span> source_location src, <span style=color:#66d9ef>const</span> std<span style=color:#f92672>::</span><span style=color:#66d9ef>uint8_t</span> base)
|
||||
</span></span><span style=display:flex><span> {
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> toml<span style=color:#f92672>::</span>read_int<span style=color:#f92672><</span>integer_type<span style=color:#f92672>></span>(str, src, base);
|
||||
</span></span><span style=display:flex><span> }
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>static</span> result<span style=color:#f92672><</span>floating_type, error_info<span style=color:#f92672>></span>
|
||||
</span></span><span style=display:flex><span> parse_float(<span style=color:#66d9ef>const</span> std<span style=color:#f92672>::</span>string<span style=color:#f92672>&</span> str, <span style=color:#66d9ef>const</span> source_location src, <span style=color:#66d9ef>const</span> <span style=color:#66d9ef>bool</span> is_hex)
|
||||
</span></span><span style=display:flex><span> {
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> toml<span style=color:#f92672>::</span>read_float<span style=color:#f92672><</span>floating_type<span style=color:#f92672>></span>(str, src, is_hex);
|
||||
</span></span><span style=display:flex><span> }
|
||||
</span></span><span style=display:flex><span>};
|
||||
</span></span></code></pre></div><h2 id=using-containers-other-than-stdvector-for-arrays>Using Containers Other Than <code>std::vector</code> for Arrays
|
||||
<a class=anchor href=#using-containers-other-than-stdvector-for-arrays>#</a></h2><p>To use a container other than <code>vector</code> (e.g., <code>std::deque</code>) for implementing TOML arrays, modify <code>array_type</code> as follows.</p><p>Similarly, to use a container other than <code>unordered_map</code> (e.g., <code>std::map</code>) for table types, modify <code>table_type</code> as shown below.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>struct</span> <span style=color:#a6e22e>deque_map_config</span>
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> comment_type <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>preserve_comments;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> boolean_type <span style=color:#f92672>=</span> <span style=color:#66d9ef>bool</span>;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> integer_type <span style=color:#f92672>=</span> std<span style=color:#f92672>::</span><span style=color:#66d9ef>int64_t</span>;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> floating_type <span style=color:#f92672>=</span> <span style=color:#66d9ef>double</span>;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> string_type <span style=color:#f92672>=</span> std<span style=color:#f92672>::</span>string;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>template</span><span style=color:#f92672><</span><span style=color:#66d9ef>typename</span> T<span style=color:#f92672>></span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> array_type <span style=color:#f92672>=</span> std<span style=color:#f92672>::</span>deque<span style=color:#f92672><</span>T<span style=color:#f92672>></span>; <span style=color:#75715e>// XXX
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span> <span style=color:#66d9ef>template</span><span style=color:#f92672><</span><span style=color:#66d9ef>typename</span> K, <span style=color:#66d9ef>typename</span> T<span style=color:#f92672>></span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> table_type <span style=color:#f92672>=</span> std<span style=color:#f92672>::</span>map<span style=color:#f92672><</span>K, T<span style=color:#f92672>></span>; <span style=color:#75715e>// XXX
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>static</span> result<span style=color:#f92672><</span>integer_type, error_info<span style=color:#f92672>></span>
|
||||
</span></span><span style=display:flex><span> parse_int(<span style=color:#66d9ef>const</span> std<span style=color:#f92672>::</span>string<span style=color:#f92672>&</span> str, <span style=color:#66d9ef>const</span> source_location src, <span style=color:#66d9ef>const</span> std<span style=color:#f92672>::</span><span style=color:#66d9ef>uint8_t</span> base)
|
||||
</span></span><span style=display:flex><span> {
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> toml<span style=color:#f92672>::</span>read_int<span style=color:#f92672><</span>integer_type<span style=color:#f92672>></span>(str, src, base);
|
||||
</span></span><span style=display:flex><span> }
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>static</span> result<span style=color:#f92672><</span>floating_type, error_info<span style=color:#f92672>></span>
|
||||
</span></span><span style=display:flex><span> parse_float(<span style=color:#66d9ef>const</span> std<span style=color:#f92672>::</span>string<span style=color:#f92672>&</span> str, <span style=color:#66d9ef>const</span> source_location src, <span style=color:#66d9ef>const</span> <span style=color:#66d9ef>bool</span> is_hex)
|
||||
</span></span><span style=display:flex><span> {
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> toml<span style=color:#f92672>::</span>read_float<span style=color:#f92672><</span>floating_type<span style=color:#f92672>></span>(str, src, is_hex);
|
||||
</span></span><span style=display:flex><span> }
|
||||
</span></span><span style=display:flex><span>};
|
||||
</span></span></code></pre></div><h2 id=using-boostmultiprecision-for-numeric-types>Using <code>boost::multiprecision</code> for Numeric Types
|
||||
<a class=anchor href=#using-boostmultiprecision-for-numeric-types>#</a></h2><p>By using <code>boost::multiprecision::cpp_int</code> and <code>boost::multiprecision::cpp_bin_float_oct</code>, you can utilize a wider integer type and a more precise floating-point type.</p><p>These types implement stream operators, so you can use the default implementations of <code>read_int</code> and <code>read_float</code> without modification.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>struct</span> <span style=color:#a6e22e>large_num_config</span>
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> comment_type <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>preserve_comments;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> boolean_type <span style=color:#f92672>=</span> <span style=color:#66d9ef>bool</span>;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> integer_type <span style=color:#f92672>=</span> boost<span style=color:#f92672>::</span>multiprecision<span style=color:#f92672>::</span>cpp_int;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> floating_type <span style=color:#f92672>=</span> boost<span style=color:#f92672>::</span>multiprecision<span style=color:#f92672>::</span>cpp_bin_float_oct;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> string_type <span style=color:#f92672>=</span> std<span style=color:#f92672>::</span>string;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>template</span><span style=color:#f92672><</span><span style=color:#66d9ef>typename</span> T<span style=color:#f92672>></span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> array_type <span style=color:#f92672>=</span> std<span style=color:#f92672>::</span>vector<span style=color:#f92672><</span>T<span style=color:#f92672>></span>;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>template</span><span style=color:#f92672><</span><span style=color:#66d9ef>typename</span> K, <span style=color:#66d9ef>typename</span> T<span style=color:#f92672>></span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> table_type <span style=color:#f92672>=</span> std<span style=color:#f92672>::</span>unordered_map<span style=color:#f92672><</span>K, T<span style=color:#f92672>></span>;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>static</span> toml<span style=color:#f92672>::</span>result<span style=color:#f92672><</span>integer_type, toml<span style=color:#f92672>::</span>error_info<span style=color:#f92672>></span>
|
||||
</span></span><span style=display:flex><span> parse_int(<span style=color:#66d9ef>const</span> std<span style=color:#f92672>::</span>string<span style=color:#f92672>&</span> str, <span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>source_location src, <span style=color:#66d9ef>const</span> std<span style=color:#f92672>::</span><span style=color:#66d9ef>uint8_t</span> base)
|
||||
</span></span><span style=display:flex><span> {
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> toml<span style=color:#f92672>::</span>read_int<span style=color:#f92672><</span>integer_type<span style=color:#f92672>></span>(str, src, base);
|
||||
</span></span><span style=display:flex><span> }
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>static</span> toml<span style=color:#f92672>::</span>result<span style=color:#f92672><</span>floating_type, toml<span style=color:#f92672>::</span>error_info<span style=color:#f92672>></span>
|
||||
</span></span><span style=display:flex><span> parse_float(<span style=color:#66d9ef>const</span> std<span style=color:#f92672>::</span>string<span style=color:#f92672>&</span> str, <span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>source_location src, <span style=color:#66d9ef>const</span> <span style=color:#66d9ef>bool</span> is_hex)
|
||||
</span></span><span style=display:flex><span> {
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> toml<span style=color:#f92672>::</span>read_float<span style=color:#f92672><</span>floating_type<span style=color:#f92672>></span>(str, src, is_hex);
|
||||
</span></span><span style=display:flex><span> }
|
||||
</span></span><span style=display:flex><span>};
|
||||
</span></span></code></pre></div></article><footer class=book-footer><div class="flex flex-wrap justify-between"></div><script>(function(){function e(e){const t=window.getSelection(),n=document.createRange();n.selectNodeContents(e),t.removeAllRanges(),t.addRange(n)}document.querySelectorAll("pre code").forEach(t=>{t.addEventListener("click",function(){if(window.getSelection().toString())return;e(t.parentElement),navigator.clipboard&&navigator.clipboard.writeText(t.parentElement.textContent)})})})()</script></footer><label for=menu-control class="hidden book-menu-overlay"></label></div><aside class=book-toc><div class=book-toc-content><nav id=TableOfContents><ul><li><a href=#customizing-types>Customizing Types</a><ul><li><a href=#type_config><code>type_config</code></a></li><li><a href=#preserving-order-of-values-in-tables>Preserving Order of Values in Tables</a></li><li><a href=#not-preserving-comments>Not Preserving Comments</a></li><li><a href=#using-containers-other-than-stdvector-for-arrays>Using Containers Other Than <code>std::vector</code> for Arrays</a></li><li><a href=#using-boostmultiprecision-for-numeric-types>Using <code>boost::multiprecision</code> for Numeric Types</a></li></ul></li></ul></nav></div></aside></main></body></html>
|
||||
124
docs/features/error_message/index.html
Normal file
124
docs/features/error_message/index.html
Normal file
@@ -0,0 +1,124 @@
|
||||
<!doctype html><html lang=en dir=ltr><head><meta charset=UTF-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="
|
||||
Outputting Error Messages
|
||||
#
|
||||
|
||||
toml11 provides error messages that include location information within the file when using functions like toml::parse, toml::get<T>/find<T>, and as_integer(), among others.
|
||||
For instance, if a syntax error in an integer is detected during parsing, an error message might look like this:
|
||||
[error] bad integer: `_` must be surrounded by digits
|
||||
--> internal string at line 64 in file main.cpp
|
||||
|
|
||||
1 | a = 123__456
|
||||
| ^-- invalid underscore
|
||||
Hint: valid : -42, 1_000, 1_2_3_4_5, 0xC0FFEE, 0b0010, 0o755
|
||||
Hint: invalid: _42, 1__000, 0123
|
||||
Or, if a type different from the one actually stored is requested:"><meta name=theme-color media="(prefers-color-scheme: light)" content="#ffffff"><meta name=theme-color media="(prefers-color-scheme: dark)" content="#343a40"><meta name=color-scheme content="light dark"><meta property="og:url" content="https://toruniina.github.io/toml11/docs/features/error_message/"><meta property="og:site_name" content="toml11"><meta property="og:title" content="error message"><meta property="og:description" content="Outputting Error Messages # toml11 provides error messages that include location information within the file when using functions like toml::parse, toml::get<T>/find<T>, and as_integer(), among others.
|
||||
For instance, if a syntax error in an integer is detected during parsing, an error message might look like this:
|
||||
[error] bad integer: `_` must be surrounded by digits --> internal string at line 64 in file main.cpp | 1 | a = 123__456 | ^-- invalid underscore Hint: valid : -42, 1_000, 1_2_3_4_5, 0xC0FFEE, 0b0010, 0o755 Hint: invalid: _42, 1__000, 0123 Or, if a type different from the one actually stored is requested:"><meta property="og:locale" content="en"><meta property="og:type" content="article"><meta property="article:section" content="docs"><title>error message | toml11</title>
|
||||
<link rel=manifest href=/toml11/manifest.json><link rel=icon href=/toml11/favicon.png><link rel=canonical href=https://toruniina.github.io/toml11/docs/features/error_message/><link rel=alternate hreflang=ja href=https://toruniina.github.io/toml11/ja/docs/features/error_message/ title="error message"><link rel=stylesheet href=/toml11/book.min.ddac3efe7ea4c1007ff53e5a8fd67f12517e5d2e99984d8c67a18668f7ecaa03.css integrity="sha256-3aw+/n6kwQB/9T5aj9Z/ElF+XS6ZmE2MZ6GGaPfsqgM=" crossorigin=anonymous><script defer src=/toml11/fuse.min.js></script><script defer src=/toml11/en.search.min.db4a558804ac41f081539588cec8e4a415587801da466728166bb5341dd62411.js integrity="sha256-20pViASsQfCBU5WIzsjkpBVYeAHaRmcoFmu1NB3WJBE=" crossorigin=anonymous></script></head><body dir=ltr><input type=checkbox class="hidden toggle" id=menu-control>
|
||||
<input type=checkbox class="hidden toggle" id=toc-control><main class="container flex"><aside class=book-menu><div class=book-menu-content><nav><h2 class=book-brand><a class="flex align-center" href=/toml11/><span>toml11</span></a></h2><div class="book-search hidden"><input type=text id=book-search-input placeholder=Search aria-label=Search maxlength=64 data-hotkeys=s/><div class="book-search-spinner hidden"></div><ul id=book-search-results></ul></div><script>document.querySelector(".book-search").classList.remove("hidden")</script><ul class=book-languages><li><input type=checkbox id=languages class=toggle>
|
||||
<label for=languages class="flex justify-between"><a role=button class="flex align-center"><img src=/toml11/svg/translate.svg class=book-icon alt=Languages>
|
||||
English</a></label><ul><li><a href=https://toruniina.github.io/toml11/ja/docs/features/error_message/>日本語</a></li></ul></li></ul><ul><li><a href=/toml11/docs/installation/>installation</a><ul></ul></li><li><input type=checkbox id=section-291123c850af98d8b815ccdbb4c33657 class=toggle checked>
|
||||
<label for=section-291123c850af98d8b815ccdbb4c33657 class="flex justify-between"><a href=/toml11/docs/features/>features</a></label><ul><li><a href=/toml11/docs/features/parsing_files/>parsing files</a></li><li><a href=/toml11/docs/features/value/>getting values</a></li><li><a href=/toml11/docs/features/error_message/ class=active>error message</a></li><li><a href=/toml11/docs/features/serialize/>serializing values</a></li><li><a href=/toml11/docs/features/configure_types/>configuring types</a></li><li><a href=/toml11/docs/features/literal/>toml literal</a></li><li><a href=/toml11/docs/features/toml_spec/>toml spec</a></li><li><a href=/toml11/docs/features/extension/>extension</a></li></ul></li><li><input type=checkbox id=section-e2e812e55021b82e114feaae98f1a02e class=toggle>
|
||||
<label for=section-e2e812e55021b82e114feaae98f1a02e class="flex justify-between"><a href=/toml11/docs/reference/>reference</a></label><ul><li><a href=/toml11/docs/reference/color/>color.hpp</a></li><li><a href=/toml11/docs/reference/comments/>comments.hpp</a></li><li><a href=/toml11/docs/reference/conversion/>conversion.hpp</a></li><li><a href=/toml11/docs/reference/datetime/>datetime.hpp</a></li><li><a href=/toml11/docs/reference/error_info/>error_info.hpp</a></li><li><a href=/toml11/docs/reference/exception/>exception.hpp</a></li><li><a href=/toml11/docs/reference/find/>find.hpp</a></li><li><a href=/toml11/docs/reference/format/>format.hpp</a></li><li><a href=/toml11/docs/reference/from/>from.hpp</a></li><li><a href=/toml11/docs/reference/get/>get.hpp</a></li><li><a href=/toml11/docs/reference/into/>into.hpp</a></li><li><a href=/toml11/docs/reference/literal/>literal.hpp</a></li><li><a href=/toml11/docs/reference/ordered_map/>ordered_map.hpp</a></li><li><a href=/toml11/docs/reference/parser/>parser.hpp</a></li><li><a href=/toml11/docs/reference/result/>result.hpp</a></li><li><a href=/toml11/docs/reference/serializer/>serializer.hpp</a></li><li><a href=/toml11/docs/reference/source_location/>source_location.hpp</a></li><li><a href=/toml11/docs/reference/spec/>spec.hpp</a></li><li><a href=/toml11/docs/reference/toml_fwd/>toml_fwd.hpp</a></li><li><a href=/toml11/docs/reference/toml/>toml.hpp</a></li><li><a href=/toml11/docs/reference/types/>types.hpp</a></li><li><a href=/toml11/docs/reference/value_t/>value_t.hpp</a></li><li><a href=/toml11/docs/reference/value/>value.hpp</a></li><li><a href=/toml11/docs/reference/version/>version.hpp</a></li><li><a href=/toml11/docs/reference/visit/>visit.hpp</a></li></ul></li><li><a href=/toml11/docs/changelog/>changelog</a><ul></ul></li></ul><ul><li><a href=https://github.com/ToruNiina/toml11 target=_blank rel=noopener>GitHub</a></li></ul></nav><script>(function(){var e=document.querySelector("aside .book-menu-content");addEventListener("beforeunload",function(){localStorage.setItem("menu.scrollTop",e.scrollTop)}),e.scrollTop=localStorage.getItem("menu.scrollTop")})()</script></div></aside><div class=book-page><header class=book-header><div class="flex align-center justify-between"><label for=menu-control><img src=/toml11/svg/menu.svg class=book-icon alt=Menu>
|
||||
</label><strong>error message</strong>
|
||||
<label for=toc-control><img src=/toml11/svg/toc.svg class=book-icon alt="Table of Contents"></label></div><aside class="hidden clearfix"><nav id=TableOfContents><ul><li><a href=#outputting-error-messages>Outputting Error Messages</a><ul><li><a href=#creating-error-messages-from-tomlvalue-location-information>Creating Error Messages from <code>toml::value</code> Location Information</a></li><li><a href=#adding-colors-to-strings>Adding Colors to Strings</a></li><li><a href=#changing-the-prefix-of-error-messages-from-error>Changing the Prefix of Error Messages from <code>[error]</code></a></li><li><a href=#creating-error-messages-referencing-multiple-tomlvalue>Creating Error Messages Referencing Multiple <code>toml::value</code></a></li></ul></li></ul></nav></aside></header><article class="markdown book-article"><h1 id=outputting-error-messages>Outputting Error Messages
|
||||
<a class=anchor href=#outputting-error-messages>#</a></h1><p><code>toml11</code> provides error messages that include location information within the file when using functions like <code>toml::parse</code>, <code>toml::get<T>/find<T></code>, and <code>as_integer()</code>, among others.</p><p>For instance, if a syntax error in an integer is detected during parsing, an error message might look like this:</p><pre tabindex=0><code>[error] bad integer: `_` must be surrounded by digits
|
||||
--> internal string at line 64 in file main.cpp
|
||||
|
|
||||
1 | a = 123__456
|
||||
| ^-- invalid underscore
|
||||
Hint: valid : -42, 1_000, 1_2_3_4_5, 0xC0FFEE, 0b0010, 0o755
|
||||
Hint: invalid: _42, 1__000, 0123
|
||||
</code></pre><p>Or, if a type different from the one actually stored is requested:</p><pre tabindex=0><code>[error] toml::value::as_string(): bad_cast to string
|
||||
--> input.toml
|
||||
|
|
||||
1 | a = 123_456
|
||||
| ^^^^^^^-- the actual type is integer
|
||||
</code></pre><p><code>toml11</code> provides methods to create such error messages from <code>toml::value</code>.</p><p>By utilizing this feature, you can inform users not only about TOML syntax errors but also about application-specific errors. For example, if a negative number appears where only positive values are allowed, you can highlight the location within the TOML file to convey the error to the user.</p><h2 id=creating-error-messages-from-tomlvalue-location-information>Creating Error Messages from <code>toml::value</code> Location Information
|
||||
<a class=anchor href=#creating-error-messages-from-tomlvalue-location-information>#</a></h2><p><code>toml::value</code> retains information about the location where it was parsed.</p><p>This information is encapsulated in <code>toml::source_location</code> and can be retrieved using <code>toml::value::location()</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>&</span> a <span style=color:#f92672>=</span> input.at(<span style=color:#e6db74>"a"</span>);
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>source_location src <span style=color:#f92672>=</span> a.location();
|
||||
</span></span></code></pre></div><p>When a file is parsed with <code>toml::parse</code>, the TOML filename and line numbers are stored.</p><p>If parsed with <code>toml::parse_str</code>, the TOML filename is not available, but instead, the filename and line number of the C++ source code that called <code>toml::parse_str</code> are stored as the TOML filename. The first example on this page was output from <code>toml::parse_str</code>. Note the filename part.</p><p>For details, see the <a href=https://toruniina.github.io/toml11/docs/reference/source_location/>reference</a>.</p><p>You can build error information by passing a <code>toml::source_location</code> or <code>toml::value</code> and the associated error message to <code>toml::make_error_info</code>. Passing this to <code>toml::format_error</code> formats the error message into a <code>std::string</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>&</span> a <span style=color:#f92672>=</span> input.at(<span style=color:#e6db74>"a"</span>);
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>if</span>(a.as_integer() <span style=color:#f92672><</span> <span style=color:#ae81ff>0</span>)
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>error_info err <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>make_error_info(
|
||||
</span></span><span style=display:flex><span> <span style=color:#e6db74>"positive integer is required"</span>, <span style=color:#75715e>// Error title
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span> a, <span style=color:#e6db74>"but got negative value"</span> <span style=color:#75715e>// Message next to the value
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span> );
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cerr <span style=color:#f92672><<</span> toml<span style=color:#f92672>::</span>format_error(err) <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><p>This will output:</p><pre tabindex=0><code>[error] positive integer is required
|
||||
--> input.toml
|
||||
|
|
||||
1 | a = -123456
|
||||
| ^^^^^^^-- but got negative value
|
||||
</code></pre><p>You can also add a supplementary message at the end. This part is not indented.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>&</span> a <span style=color:#f92672>=</span> input.at(<span style=color:#e6db74>"a"</span>);
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>if</span>(a.as_integer() <span style=color:#f92672><</span> <span style=color:#ae81ff>0</span>)
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>error_info err <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>make_error_info(
|
||||
</span></span><span style=display:flex><span> <span style=color:#e6db74>"positive integer is required"</span>, <span style=color:#75715e>// Error title
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span> a, <span style=color:#e6db74>"but got negative value"</span>, <span style=color:#75715e>// Message next to the value
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span> <span style=color:#e6db74>"Hint: `a` means length of the data"</span> <span style=color:#75715e>// Supplementary message
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span> );
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cerr <span style=color:#f92672><<</span> toml<span style=color:#f92672>::</span>format_error(err) <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><p>This will output:</p><pre tabindex=0><code>[error] positive integer is required
|
||||
--> input.toml
|
||||
|
|
||||
1 | a = -123456
|
||||
| ^^^^^^^-- but got negative value
|
||||
Hint: `a` means length of the data
|
||||
</code></pre><blockquote class="book-hint info"><p>The ability to output lines from the file using <code>toml::value</code> is because the parsed file is retained in memory as a string.</p><p>The parsed string is shared by <code>toml::value</code> via a <code>std::shared_ptr</code>. Copying it does not duplicate the entire file string. The file information is freed from memory when all <code>toml::value</code> instances constructed from parsing the file are destructed.</p><p>Therefore, when using this in an application, it is recommended to extract and store the required values during loading rather than directly storing <code>toml::value</code>.</p></blockquote><h2 id=adding-colors-to-strings>Adding Colors to Strings
|
||||
<a class=anchor href=#adding-colors-to-strings>#</a></h2><p>You can add color to error messages using ANSI escape codes.</p><p>If <code>TOML11_COLORIZE_ERROR_MESSAGE</code> is defined at compile time, the error messages output by toml11 will be colored by default.</p><p>If not, you can enable color for subsequent error messages by calling <code>toml::color::enable()</code>. Conversely, if you do not want colored output, for example, because the output is not to a console, call <code>toml::color::disable()</code>. You can check whether coloring is enabled at any point by calling <code>toml::color::should_color()</code>.</p><p>Additionally, while the error title, error message, and supplementary information are not colored by default, you can use manipulators from toml::color to add color to them.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>std<span style=color:#f92672>::</span>ostringstream oss;
|
||||
</span></span><span style=display:flex><span>oss <span style=color:#f92672><<</span> toml<span style=color:#f92672>::</span>color<span style=color:#f92672>::</span>red <span style=color:#f92672><<</span> <span style=color:#e6db74>"but got negative value"</span>;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>error_info err <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>make_error_info(
|
||||
</span></span><span style=display:flex><span> <span style=color:#e6db74>"positive integer is required"</span>, <span style=color:#75715e>// Error title
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span> a, oss.str(), <span style=color:#75715e>// Message next to the value
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span> <span style=color:#e6db74>"Hint: `a` means length of the data"</span> <span style=color:#75715e>// Supplementary message
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span> );
|
||||
</span></span></code></pre></div><p>For more details, see the <a href=https://toruniina.github.io/toml11/docs/reference/color/>reference</a>.</p><h2 id=changing-the-prefix-of-error-messages-from-error>Changing the Prefix of Error Messages from <code>[error]</code>
|
||||
<a class=anchor href=#changing-the-prefix-of-error-messages-from-error>#</a></h2><p>There may be different types of errors, and the default <code>[error]</code> prefix might not always be appropriate.</p><p>With <code>toml::format_error</code>, you can provide a <code>std::string</code> before <code>toml::error_info</code> to replace the <code>[error]</code> prefix.</p><p>For example:</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>&</span> a <span style=color:#f92672>=</span> input.at(<span style=color:#e6db74>"a"</span>);
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>if</span>(a.as_integer() <span style=color:#f92672><</span> <span style=color:#ae81ff>0</span>)
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>error_info err <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>make_error_info(
|
||||
</span></span><span style=display:flex><span> <span style=color:#e6db74>"positive integer is required"</span>, <span style=color:#75715e>// Error title
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span> a, <span style=color:#e6db74>"but got negative value"</span> <span style=color:#75715e>// Message next to the value
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span> );
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>ostringstream prefix;
|
||||
</span></span><span style=display:flex><span> prefix <span style=color:#f92672><<</span> toml<span style=color:#f92672>::</span>color<span style=color:#f92672>::</span>bold <span style=color:#f92672><<</span> toml<span style=color:#f92672>::</span>color<span style=color:#f92672>::</span>yellow <span style=color:#f92672><<</span> <span style=color:#e6db74>"[warn]"</span>;
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cerr <span style=color:#f92672><<</span> toml<span style=color:#f92672>::</span>format_error(prefix.str(), err) <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> <span style=color:#ae81ff>0</span>;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>else</span>
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> a.as_integer();
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><p>This will output a warning starting with <code>[warn]</code>.</p><p>Additionally, you can create error messages without the <code>[error]</code> prefix by directly passing the components of <code>error_info</code> to <code>toml::format_error</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>&</span> a <span style=color:#f92672>=</span> input.at(<span style=color:#e6db74>"a"</span>);
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>if</span>(a.as_integer() <span style=color:#f92672><</span> <span style=color:#ae81ff>0</span>)
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cerr <span style=color:#f92672><<</span> toml<span style=color:#f92672>::</span>format_error(
|
||||
</span></span><span style=display:flex><span> <span style=color:#e6db74>"[warn] positive integer is required"</span>, <span style=color:#75715e>// Error title
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span> a, <span style=color:#e6db74>"but got negative value"</span> <span style=color:#75715e>// Message next to the value
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span> ) <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> <span style=color:#ae81ff>0</span>;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>else</span>
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> a.as_integer()
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><h2 id=creating-error-messages-referencing-multiple-tomlvalue>Creating Error Messages Referencing Multiple <code>toml::value</code>
|
||||
<a class=anchor href=#creating-error-messages-referencing-multiple-tomlvalue>#</a></h2><p>In application settings, the range of permissible values might change based on previously read values.</p><p>In such cases, you may want to output the values causing the error simultaneously.</p><p><code>toml::format_error</code> and <code>toml::make_error_info</code> can take multiple pairs of <code>toml::value</code> and their corresponding error messages as <code>std::string</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>std<span style=color:#f92672>::</span>cerr <span style=color:#f92672><<</span> toml<span style=color:#f92672>::</span>format_error(
|
||||
</span></span><span style=display:flex><span> <span style=color:#e6db74>"[error] invalid range"</span>,
|
||||
</span></span><span style=display:flex><span> a, <span style=color:#e6db74>"minimum value is defined here"</span>,
|
||||
</span></span><span style=display:flex><span> b, <span style=color:#e6db74>"maximum value is defined here"</span>,
|
||||
</span></span><span style=display:flex><span> c, <span style=color:#e6db74>"and it exceeds the range"</span>
|
||||
</span></span><span style=display:flex><span> ) <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span></code></pre></div><p>You can also add supplementary information at the end.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>std<span style=color:#f92672>::</span>cerr <span style=color:#f92672><<</span> toml<span style=color:#f92672>::</span>format_error(
|
||||
</span></span><span style=display:flex><span> <span style=color:#e6db74>"[error] invalid range"</span>,
|
||||
</span></span><span style=display:flex><span> a, <span style=color:#e6db74>"minimum value is defined here"</span>,
|
||||
</span></span><span style=display:flex><span> b, <span style=color:#e6db74>"maximum value is defined here"</span>,
|
||||
</span></span><span style=display:flex><span> c, <span style=color:#e6db74>"and it exceeds the range"</span>,
|
||||
</span></span><span style=display:flex><span> <span style=color:#e6db74>"Hint: all the values must be in the range [a, b)"</span>
|
||||
</span></span><span style=display:flex><span> ) <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span></code></pre></div><p>When passing <code>toml::value</code> or <code>toml::source_location</code>, an error message related to it must follow. If not, it will result in a very confusing compilation error.</p></article><footer class=book-footer><div class="flex flex-wrap justify-between"></div><script>(function(){function e(e){const t=window.getSelection(),n=document.createRange();n.selectNodeContents(e),t.removeAllRanges(),t.addRange(n)}document.querySelectorAll("pre code").forEach(t=>{t.addEventListener("click",function(){if(window.getSelection().toString())return;e(t.parentElement),navigator.clipboard&&navigator.clipboard.writeText(t.parentElement.textContent)})})})()</script></footer><label for=menu-control class="hidden book-menu-overlay"></label></div><aside class=book-toc><div class=book-toc-content><nav id=TableOfContents><ul><li><a href=#outputting-error-messages>Outputting Error Messages</a><ul><li><a href=#creating-error-messages-from-tomlvalue-location-information>Creating Error Messages from <code>toml::value</code> Location Information</a></li><li><a href=#adding-colors-to-strings>Adding Colors to Strings</a></li><li><a href=#changing-the-prefix-of-error-messages-from-error>Changing the Prefix of Error Messages from <code>[error]</code></a></li><li><a href=#creating-error-messages-referencing-multiple-tomlvalue>Creating Error Messages Referencing Multiple <code>toml::value</code></a></li></ul></li></ul></nav></div></aside></main></body></html>
|
||||
73
docs/features/extension/index.html
Normal file
73
docs/features/extension/index.html
Normal file
@@ -0,0 +1,73 @@
|
||||
<!doctype html><html lang=en dir=ltr><head><meta charset=UTF-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="
|
||||
TOML Language Extensions
|
||||
#
|
||||
|
||||
The TOML language is currently at version v1.0.0, but several new features have been discussed and merged, with ongoing discussions for v1.1.0.
|
||||
Among the proposed features, some were deemed to have limited use cases, some faced implementation challenges in their proposed form, and others were not adopted at all.
|
||||
In toml11, we have experimentally implemented a selection of these features. Please note that these features are supported in toml11 but are not supported by other parsers and are unlikely to be supported in the future."><meta name=theme-color media="(prefers-color-scheme: light)" content="#ffffff"><meta name=theme-color media="(prefers-color-scheme: dark)" content="#343a40"><meta name=color-scheme content="light dark"><meta property="og:url" content="https://toruniina.github.io/toml11/docs/features/extension/"><meta property="og:site_name" content="toml11"><meta property="og:title" content="extension"><meta property="og:description" content="TOML Language Extensions # The TOML language is currently at version v1.0.0, but several new features have been discussed and merged, with ongoing discussions for v1.1.0.
|
||||
Among the proposed features, some were deemed to have limited use cases, some faced implementation challenges in their proposed form, and others were not adopted at all.
|
||||
In toml11, we have experimentally implemented a selection of these features. Please note that these features are supported in toml11 but are not supported by other parsers and are unlikely to be supported in the future."><meta property="og:locale" content="en"><meta property="og:type" content="article"><meta property="article:section" content="docs"><title>extension | toml11</title>
|
||||
<link rel=manifest href=/toml11/manifest.json><link rel=icon href=/toml11/favicon.png><link rel=canonical href=https://toruniina.github.io/toml11/docs/features/extension/><link rel=alternate hreflang=ja href=https://toruniina.github.io/toml11/ja/docs/features/extension/ title=extension><link rel=stylesheet href=/toml11/book.min.ddac3efe7ea4c1007ff53e5a8fd67f12517e5d2e99984d8c67a18668f7ecaa03.css integrity="sha256-3aw+/n6kwQB/9T5aj9Z/ElF+XS6ZmE2MZ6GGaPfsqgM=" crossorigin=anonymous><script defer src=/toml11/fuse.min.js></script><script defer src=/toml11/en.search.min.db4a558804ac41f081539588cec8e4a415587801da466728166bb5341dd62411.js integrity="sha256-20pViASsQfCBU5WIzsjkpBVYeAHaRmcoFmu1NB3WJBE=" crossorigin=anonymous></script></head><body dir=ltr><input type=checkbox class="hidden toggle" id=menu-control>
|
||||
<input type=checkbox class="hidden toggle" id=toc-control><main class="container flex"><aside class=book-menu><div class=book-menu-content><nav><h2 class=book-brand><a class="flex align-center" href=/toml11/><span>toml11</span></a></h2><div class="book-search hidden"><input type=text id=book-search-input placeholder=Search aria-label=Search maxlength=64 data-hotkeys=s/><div class="book-search-spinner hidden"></div><ul id=book-search-results></ul></div><script>document.querySelector(".book-search").classList.remove("hidden")</script><ul class=book-languages><li><input type=checkbox id=languages class=toggle>
|
||||
<label for=languages class="flex justify-between"><a role=button class="flex align-center"><img src=/toml11/svg/translate.svg class=book-icon alt=Languages>
|
||||
English</a></label><ul><li><a href=https://toruniina.github.io/toml11/ja/docs/features/extension/>日本語</a></li></ul></li></ul><ul><li><a href=/toml11/docs/installation/>installation</a><ul></ul></li><li><input type=checkbox id=section-291123c850af98d8b815ccdbb4c33657 class=toggle checked>
|
||||
<label for=section-291123c850af98d8b815ccdbb4c33657 class="flex justify-between"><a href=/toml11/docs/features/>features</a></label><ul><li><a href=/toml11/docs/features/parsing_files/>parsing files</a></li><li><a href=/toml11/docs/features/value/>getting values</a></li><li><a href=/toml11/docs/features/error_message/>error message</a></li><li><a href=/toml11/docs/features/serialize/>serializing values</a></li><li><a href=/toml11/docs/features/configure_types/>configuring types</a></li><li><a href=/toml11/docs/features/literal/>toml literal</a></li><li><a href=/toml11/docs/features/toml_spec/>toml spec</a></li><li><a href=/toml11/docs/features/extension/ class=active>extension</a></li></ul></li><li><input type=checkbox id=section-e2e812e55021b82e114feaae98f1a02e class=toggle>
|
||||
<label for=section-e2e812e55021b82e114feaae98f1a02e class="flex justify-between"><a href=/toml11/docs/reference/>reference</a></label><ul><li><a href=/toml11/docs/reference/color/>color.hpp</a></li><li><a href=/toml11/docs/reference/comments/>comments.hpp</a></li><li><a href=/toml11/docs/reference/conversion/>conversion.hpp</a></li><li><a href=/toml11/docs/reference/datetime/>datetime.hpp</a></li><li><a href=/toml11/docs/reference/error_info/>error_info.hpp</a></li><li><a href=/toml11/docs/reference/exception/>exception.hpp</a></li><li><a href=/toml11/docs/reference/find/>find.hpp</a></li><li><a href=/toml11/docs/reference/format/>format.hpp</a></li><li><a href=/toml11/docs/reference/from/>from.hpp</a></li><li><a href=/toml11/docs/reference/get/>get.hpp</a></li><li><a href=/toml11/docs/reference/into/>into.hpp</a></li><li><a href=/toml11/docs/reference/literal/>literal.hpp</a></li><li><a href=/toml11/docs/reference/ordered_map/>ordered_map.hpp</a></li><li><a href=/toml11/docs/reference/parser/>parser.hpp</a></li><li><a href=/toml11/docs/reference/result/>result.hpp</a></li><li><a href=/toml11/docs/reference/serializer/>serializer.hpp</a></li><li><a href=/toml11/docs/reference/source_location/>source_location.hpp</a></li><li><a href=/toml11/docs/reference/spec/>spec.hpp</a></li><li><a href=/toml11/docs/reference/toml_fwd/>toml_fwd.hpp</a></li><li><a href=/toml11/docs/reference/toml/>toml.hpp</a></li><li><a href=/toml11/docs/reference/types/>types.hpp</a></li><li><a href=/toml11/docs/reference/value_t/>value_t.hpp</a></li><li><a href=/toml11/docs/reference/value/>value.hpp</a></li><li><a href=/toml11/docs/reference/version/>version.hpp</a></li><li><a href=/toml11/docs/reference/visit/>visit.hpp</a></li></ul></li><li><a href=/toml11/docs/changelog/>changelog</a><ul></ul></li></ul><ul><li><a href=https://github.com/ToruNiina/toml11 target=_blank rel=noopener>GitHub</a></li></ul></nav><script>(function(){var e=document.querySelector("aside .book-menu-content");addEventListener("beforeunload",function(){localStorage.setItem("menu.scrollTop",e.scrollTop)}),e.scrollTop=localStorage.getItem("menu.scrollTop")})()</script></div></aside><div class=book-page><header class=book-header><div class="flex align-center justify-between"><label for=menu-control><img src=/toml11/svg/menu.svg class=book-icon alt=Menu>
|
||||
</label><strong>extension</strong>
|
||||
<label for=toc-control><img src=/toml11/svg/toc.svg class=book-icon alt="Table of Contents"></label></div><aside class="hidden clearfix"><nav id=TableOfContents><ul><li><a href=#toml-language-extensions>TOML Language Extensions</a><ul><li><a href=#null><code>null</code></a></li><li><a href=#hexadecimal-format-for-floating-point-numbers>Hexadecimal Format for Floating-Point Numbers</a></li><li><a href=#suffixes-for-integers-and-floating-point-numbers>Suffixes for Integers and Floating-Point Numbers</a></li></ul></li></ul></nav></aside></header><article class="markdown book-article"><h1 id=toml-language-extensions>TOML Language Extensions
|
||||
<a class=anchor href=#toml-language-extensions>#</a></h1><p>The TOML language is currently at version v1.0.0, but several new features have been discussed and merged, with ongoing discussions for v1.1.0.</p><p>Among the proposed features, some were deemed to have limited use cases, some faced implementation challenges in their proposed form, and others were not adopted at all.</p><p>In toml11, we have experimentally implemented a selection of these features. Please note that these features are supported in toml11 but are not supported by other parsers and are unlikely to be supported in the future.</p><p>Additionally, these features are disabled by default. To use them, you must explicitly set the corresponding feature flags to <code>true</code>. This design choice ensures that non-standard features are only used intentionally.</p><p>Some of these features may eventually be merged into the TOML language itself. If a feature is officially adopted, the corresponding experimental implementation in toml11 may be removed in a minor version update after the official feature is implemented.</p><h2 id=null><code>null</code>
|
||||
<a class=anchor href=#null>#</a></h2><p>This feature allows the use of <code>null</code> as a value in TOML files.</p><pre tabindex=0><code>a = null
|
||||
b = [ 1, 2, 3, null, 5]
|
||||
</code></pre><p>To enable this, set the <code>ext_null_value</code> flag in <code>toml::spec</code> to <code>true</code>.</p><p>When parsed, it will be treated as <code>toml::value_t::empty</code>, similar to a default-constructed value. However, the location information within the file will be set.</p><p><code>null</code> is parsed only in the context of values. Therefore, if <code>null</code> is used as a key, it will be interpreted as the string <code>"null"</code>, as it has been in the standard TOML.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><toml.hpp></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>int</span> <span style=color:#a6e22e>main</span>()
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> toml<span style=color:#f92672>::</span>spec spec;
|
||||
</span></span><span style=display:flex><span> spec.ext_null_value <span style=color:#f92672>=</span> true;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> v <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse_str(<span style=color:#e6db74>"a = null"</span>, spec);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> assert(v.at(<span style=color:#e6db74>"a"</span>).is_empty());
|
||||
</span></span><span style=display:flex><span> assert(v.at(<span style=color:#e6db74>"a"</span>).is(toml<span style=color:#f92672>::</span>value_t<span style=color:#f92672>::</span>empty));
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> <span style=color:#ae81ff>0</span>;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><h2 id=hexadecimal-format-for-floating-point-numbers>Hexadecimal Format for Floating-Point Numbers
|
||||
<a class=anchor href=#hexadecimal-format-for-floating-point-numbers>#</a></h2><p>This feature allows the use of hexadecimal format for floating-point numbers in TOML files.</p><pre tabindex=0><code>a = 0x1.91eb851eb851fp+1 # 3.14
|
||||
</code></pre><p>To enable this, set the <code>ext_hex_float</code> flag in <code>toml::spec</code> to <code>true</code>.</p><p>The format follows the <code>printf</code> specification for <code>%a/%A</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><toml.hpp></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>int</span> <span style=color:#a6e22e>main</span>()
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> toml<span style=color:#f92672>::</span>spec spec;
|
||||
</span></span><span style=display:flex><span> spec.ext_hex_float <span style=color:#f92672>=</span> true;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> v <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse_str(<span style=color:#e6db74>"a = 0x1.91eb851eb851fp+1"</span>, spec);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> assert(v.at(<span style=color:#e6db74>"a"</span>).is_floating());
|
||||
</span></span><span style=display:flex><span> assert(v.at(<span style=color:#e6db74>"a"</span>).as_floating() <span style=color:#f92672>==</span> <span style=color:#ae81ff>3.14</span>);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> <span style=color:#ae81ff>0</span>;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><h2 id=suffixes-for-integers-and-floating-point-numbers>Suffixes for Integers and Floating-Point Numbers
|
||||
<a class=anchor href=#suffixes-for-integers-and-floating-point-numbers>#</a></h2><p>This feature allows the use of suffixes for numbers in TOML files. It can be applied to integers and floating-point numbers in decimal notation.</p><p>This is particularly useful for displaying units.</p><pre tabindex=0><code>a = 86_400_sec
|
||||
b = 3.1416_rad
|
||||
c = 10_μm
|
||||
</code></pre><p>However, these are purely suffixes and do not perform any unit conversion. If unit conversion is needed, users should implement it by referencing the suffix.</p><p>To enable this, set the <code>ext_num_suffix</code> flag in <code>toml::spec</code> to <code>true</code>.</p><p>The suffix must be separated from the number by an underscore (<code>_</code>).</p><p>For clarity, the suffix cannot start with a digit.</p><pre tabindex=0><code>distance = 100_m # valid
|
||||
distance = 10_0m # invalid
|
||||
distance = 10_0_m # valid
|
||||
</code></pre><p>The suffix is stored as <code>std::string suffix</code> in the format information.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><toml.hpp></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>int</span> <span style=color:#a6e22e>main</span>()
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> toml<span style=color:#f92672>::</span>spec spec;
|
||||
</span></span><span style=display:flex><span> spec.ext_hex_float <span style=color:#f92672>=</span> true;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> v <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse_str(<span style=color:#e6db74>"a = 86_400_sec"</span>, spec);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> assert(v.at(<span style=color:#e6db74>"a"</span>).is_integer());
|
||||
</span></span><span style=display:flex><span> assert(v.at(<span style=color:#e6db74>"a"</span>).as_integer() <span style=color:#f92672>==</span> <span style=color:#ae81ff>86400</span>);
|
||||
</span></span><span style=display:flex><span> assert(v.at(<span style=color:#e6db74>"a"</span>).as_integer_fmt().suffix <span style=color:#f92672>==</span> <span style=color:#e6db74>"sec"</span>);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> <span style=color:#ae81ff>0</span>;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div></article><footer class=book-footer><div class="flex flex-wrap justify-between"></div><script>(function(){function e(e){const t=window.getSelection(),n=document.createRange();n.selectNodeContents(e),t.removeAllRanges(),t.addRange(n)}document.querySelectorAll("pre code").forEach(t=>{t.addEventListener("click",function(){if(window.getSelection().toString())return;e(t.parentElement),navigator.clipboard&&navigator.clipboard.writeText(t.parentElement.textContent)})})})()</script></footer><label for=menu-control class="hidden book-menu-overlay"></label></div><aside class=book-toc><div class=book-toc-content><nav id=TableOfContents><ul><li><a href=#toml-language-extensions>TOML Language Extensions</a><ul><li><a href=#null><code>null</code></a></li><li><a href=#hexadecimal-format-for-floating-point-numbers>Hexadecimal Format for Floating-Point Numbers</a></li><li><a href=#suffixes-for-integers-and-floating-point-numbers>Suffixes for Integers and Floating-Point Numbers</a></li></ul></li></ul></nav></div></aside></main></body></html>
|
||||
44
docs/features/index.html
Normal file
44
docs/features/index.html
Normal file
@@ -0,0 +1,44 @@
|
||||
<!doctype html><html lang=en dir=ltr><head><meta charset=UTF-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="
|
||||
Features
|
||||
#
|
||||
|
||||
This section explains the main features provided by toml11, with examples.
|
||||
|
||||
Parsing Files and Strings
|
||||
#
|
||||
|
||||
Describes the functions for parsing files and strings, and how to handle the errors they produce.
|
||||
Includes:
|
||||
|
||||
Parsing files
|
||||
Parsing strings
|
||||
Parsing byte arrays
|
||||
Parsing files without throwing exceptions
|
||||
Parsing strings without throwing exceptions
|
||||
Parsing byte arrays without throwing exceptions
|
||||
|
||||
|
||||
Extracting Values from toml::value
|
||||
#
|
||||
|
||||
Explains how to examine, extract, and convert the data types held by toml::value."><meta name=theme-color media="(prefers-color-scheme: light)" content="#ffffff"><meta name=theme-color media="(prefers-color-scheme: dark)" content="#343a40"><meta name=color-scheme content="light dark"><meta property="og:url" content="https://toruniina.github.io/toml11/docs/features/"><meta property="og:site_name" content="toml11"><meta property="og:title" content="features"><meta property="og:description" content="Features # This section explains the main features provided by toml11, with examples.
|
||||
Parsing Files and Strings # Describes the functions for parsing files and strings, and how to handle the errors they produce.
|
||||
Includes:
|
||||
Parsing files Parsing strings Parsing byte arrays Parsing files without throwing exceptions Parsing strings without throwing exceptions Parsing byte arrays without throwing exceptions Extracting Values from toml::value # Explains how to examine, extract, and convert the data types held by toml::value."><meta property="og:locale" content="en"><meta property="og:type" content="website"><title>features | toml11</title>
|
||||
<link rel=manifest href=/toml11/manifest.json><link rel=icon href=/toml11/favicon.png><link rel=canonical href=https://toruniina.github.io/toml11/docs/features/><link rel=alternate hreflang=ja href=https://toruniina.github.io/toml11/ja/docs/features/ title=features><link rel=stylesheet href=/toml11/book.min.ddac3efe7ea4c1007ff53e5a8fd67f12517e5d2e99984d8c67a18668f7ecaa03.css integrity="sha256-3aw+/n6kwQB/9T5aj9Z/ElF+XS6ZmE2MZ6GGaPfsqgM=" crossorigin=anonymous><script defer src=/toml11/fuse.min.js></script><script defer src=/toml11/en.search.min.db4a558804ac41f081539588cec8e4a415587801da466728166bb5341dd62411.js integrity="sha256-20pViASsQfCBU5WIzsjkpBVYeAHaRmcoFmu1NB3WJBE=" crossorigin=anonymous></script><link rel=alternate type=application/rss+xml href=https://toruniina.github.io/toml11/docs/features/index.xml title=toml11></head><body dir=ltr><input type=checkbox class="hidden toggle" id=menu-control>
|
||||
<input type=checkbox class="hidden toggle" id=toc-control><main class="container flex"><aside class=book-menu><div class=book-menu-content><nav><h2 class=book-brand><a class="flex align-center" href=/toml11/><span>toml11</span></a></h2><div class="book-search hidden"><input type=text id=book-search-input placeholder=Search aria-label=Search maxlength=64 data-hotkeys=s/><div class="book-search-spinner hidden"></div><ul id=book-search-results></ul></div><script>document.querySelector(".book-search").classList.remove("hidden")</script><ul class=book-languages><li><input type=checkbox id=languages class=toggle>
|
||||
<label for=languages class="flex justify-between"><a role=button class="flex align-center"><img src=/toml11/svg/translate.svg class=book-icon alt=Languages>
|
||||
English</a></label><ul><li><a href=https://toruniina.github.io/toml11/ja/docs/features/>日本語</a></li></ul></li></ul><ul><li><a href=/toml11/docs/installation/>installation</a><ul></ul></li><li><input type=checkbox id=section-291123c850af98d8b815ccdbb4c33657 class=toggle checked>
|
||||
<label for=section-291123c850af98d8b815ccdbb4c33657 class="flex justify-between"><a href=/toml11/docs/features/ class=active>features</a></label><ul><li><a href=/toml11/docs/features/parsing_files/>parsing files</a></li><li><a href=/toml11/docs/features/value/>getting values</a></li><li><a href=/toml11/docs/features/error_message/>error message</a></li><li><a href=/toml11/docs/features/serialize/>serializing values</a></li><li><a href=/toml11/docs/features/configure_types/>configuring types</a></li><li><a href=/toml11/docs/features/literal/>toml literal</a></li><li><a href=/toml11/docs/features/toml_spec/>toml spec</a></li><li><a href=/toml11/docs/features/extension/>extension</a></li></ul></li><li><input type=checkbox id=section-e2e812e55021b82e114feaae98f1a02e class=toggle>
|
||||
<label for=section-e2e812e55021b82e114feaae98f1a02e class="flex justify-between"><a href=/toml11/docs/reference/>reference</a></label><ul><li><a href=/toml11/docs/reference/color/>color.hpp</a></li><li><a href=/toml11/docs/reference/comments/>comments.hpp</a></li><li><a href=/toml11/docs/reference/conversion/>conversion.hpp</a></li><li><a href=/toml11/docs/reference/datetime/>datetime.hpp</a></li><li><a href=/toml11/docs/reference/error_info/>error_info.hpp</a></li><li><a href=/toml11/docs/reference/exception/>exception.hpp</a></li><li><a href=/toml11/docs/reference/find/>find.hpp</a></li><li><a href=/toml11/docs/reference/format/>format.hpp</a></li><li><a href=/toml11/docs/reference/from/>from.hpp</a></li><li><a href=/toml11/docs/reference/get/>get.hpp</a></li><li><a href=/toml11/docs/reference/into/>into.hpp</a></li><li><a href=/toml11/docs/reference/literal/>literal.hpp</a></li><li><a href=/toml11/docs/reference/ordered_map/>ordered_map.hpp</a></li><li><a href=/toml11/docs/reference/parser/>parser.hpp</a></li><li><a href=/toml11/docs/reference/result/>result.hpp</a></li><li><a href=/toml11/docs/reference/serializer/>serializer.hpp</a></li><li><a href=/toml11/docs/reference/source_location/>source_location.hpp</a></li><li><a href=/toml11/docs/reference/spec/>spec.hpp</a></li><li><a href=/toml11/docs/reference/toml_fwd/>toml_fwd.hpp</a></li><li><a href=/toml11/docs/reference/toml/>toml.hpp</a></li><li><a href=/toml11/docs/reference/types/>types.hpp</a></li><li><a href=/toml11/docs/reference/value_t/>value_t.hpp</a></li><li><a href=/toml11/docs/reference/value/>value.hpp</a></li><li><a href=/toml11/docs/reference/version/>version.hpp</a></li><li><a href=/toml11/docs/reference/visit/>visit.hpp</a></li></ul></li><li><a href=/toml11/docs/changelog/>changelog</a><ul></ul></li></ul><ul><li><a href=https://github.com/ToruNiina/toml11 target=_blank rel=noopener>GitHub</a></li></ul></nav><script>(function(){var e=document.querySelector("aside .book-menu-content");addEventListener("beforeunload",function(){localStorage.setItem("menu.scrollTop",e.scrollTop)}),e.scrollTop=localStorage.getItem("menu.scrollTop")})()</script></div></aside><div class=book-page><header class=book-header><div class="flex align-center justify-between"><label for=menu-control><img src=/toml11/svg/menu.svg class=book-icon alt=Menu>
|
||||
</label><strong>features</strong>
|
||||
<label for=toc-control><img src=/toml11/svg/toc.svg class=book-icon alt="Table of Contents"></label></div><aside class="hidden clearfix"><nav id=TableOfContents><ul><li><a href=#features>Features</a><ul><li><a href=#parsing-files-and-strings><a href=parsing_files>Parsing Files and Strings</a></a></li><li><a href=#extracting-values-from><a href=value>Extracting Values from <code>toml::value</code></a></a></li><li><a href=#creating-error-messages><a href=error_message>Creating Error Messages</a></a></li><li><a href=#serializing-toml-files><a href=serialize>Serializing TOML Files</a></a></li><li><a href=#configuring-types-of><a href=configure_types>Configuring Types of <code>toml::value</code></a></a></li><li><a href=#toml-literals><a href=literal>TOML Literals</a></a></li><li><a href=#toml-language-version><a href=toml_spec>TOML Language Version</a></a></li><li><a href=#toml-language-extensions><a href=extension>TOML Language Extensions</a></a></li></ul></li></ul></nav></aside></header><article class="markdown book-article"><h1 id=features>Features
|
||||
<a class=anchor href=#features>#</a></h1><p>This section explains the main features provided by toml11, with examples.</p><h2 id=parsing-files-and-strings><a href=parsing_files>Parsing Files and Strings</a>
|
||||
<a class=anchor href=#parsing-files-and-strings>#</a></h2><p>Describes the functions for parsing files and strings, and how to handle the errors they produce.</p><p>Includes:</p><ul><li>Parsing files</li><li>Parsing strings</li><li>Parsing byte arrays</li><li>Parsing files without throwing exceptions</li><li>Parsing strings without throwing exceptions</li><li>Parsing byte arrays without throwing exceptions</li></ul><h2 id=extracting-values-from><a href=value>Extracting Values from <code>toml::value</code></a>
|
||||
<a class=anchor href=#extracting-values-from>#</a></h2><p>Explains how to examine, extract, and convert the data types held by <code>toml::value</code>.</p><p>Includes:</p><ul><li>Checking the type of a value using member functions</li><li>Accessing values using member functions</li><li>Accessing comments</li><li>Handling inline tables and dotted keys</li><li>Handling date information</li><li>Using <code>toml::get<T></code> for conversion</li><li>Using <code>toml::get_or</code> to specify a fallback value</li><li>Using <code>toml::find<T></code> for searching and conversion</li><li>Using <code>toml::find_or</code> to specify a fallback value</li><li>Defining conversions with user-defined types</li><li>Applying functions with <code>toml::visit</code></li><li>Constructing <code>toml::value</code></li></ul><h2 id=creating-error-messages><a href=error_message>Creating Error Messages</a>
|
||||
<a class=anchor href=#creating-error-messages>#</a></h2><p>Explains how to generate error messages with location information from a TOML file using <code>toml::value</code>.</p><p>Includes:</p><ul><li>Extracting location information from <code>toml::value</code></li><li>Constructing error messages</li><li>Adding color to the output</li></ul><h2 id=serializing-toml-files><a href=serialize>Serializing TOML Files</a>
|
||||
<a class=anchor href=#serializing-toml-files>#</a></h2><p>Describes how to format the values of <code>toml::value</code> and the available formatting options.</p><p>Includes:</p><ul><li>Specifying formats for each value of <code>toml::value</code></li><li>Formatting <code>toml::value</code> into a string</li></ul><h2 id=configuring-types-of><a href=configure_types>Configuring Types of <code>toml::value</code></a>
|
||||
<a class=anchor href=#configuring-types-of>#</a></h2><p>Explains how to customize the types stored in <code>toml::value</code> (such as <code>integer_type</code> and <code>table_type</code>).</p><p>Includes:</p><ul><li>Defining <code>type_config</code></li><li>Using <code>ordered_type_config</code></li><li>Disabling comment preservation</li><li>Using different containers like <code>std::deque</code></li><li>Using different numeric types like <code>boost::multiprecision</code></li></ul><h2 id=toml-literals><a href=literal>TOML Literals</a>
|
||||
<a class=anchor href=#toml-literals>#</a></h2><p>Explains the <code>_toml</code> literal for embedding TOML files directly in C++ code.</p><p>Includes:</p><ul><li>Using TOML literals</li></ul><h2 id=toml-language-version><a href=toml_spec>TOML Language Version</a>
|
||||
<a class=anchor href=#toml-language-version>#</a></h2><p>Describes the versions of the TOML language supported by toml11 and how to control language features added in TOML-v1.1.0.</p><p>Includes:</p><ul><li>Using TOML language version 1.1.0</li><li>Using specific features of TOML language version 1.1.0</li></ul><h2 id=toml-language-extensions><a href=extension>TOML Language Extensions</a>
|
||||
<a class=anchor href=#toml-language-extensions>#</a></h2><p>Explains the custom extensions to the TOML language provided by toml11.</p><p>Includes:</p><ul><li>Supporting <code>null</code></li><li>Supporting hexadecimal format for floating-point numbers</li><li>Allowing units for numbers</li></ul></article><footer class=book-footer><div class="flex flex-wrap justify-between"></div><script>(function(){function e(e){const t=window.getSelection(),n=document.createRange();n.selectNodeContents(e),t.removeAllRanges(),t.addRange(n)}document.querySelectorAll("pre code").forEach(t=>{t.addEventListener("click",function(){if(window.getSelection().toString())return;e(t.parentElement),navigator.clipboard&&navigator.clipboard.writeText(t.parentElement.textContent)})})})()</script></footer><label for=menu-control class="hidden book-menu-overlay"></label></div><aside class=book-toc><div class=book-toc-content><nav id=TableOfContents><ul><li><a href=#features>Features</a><ul><li><a href=#parsing-files-and-strings><a href=parsing_files>Parsing Files and Strings</a></a></li><li><a href=#extracting-values-from><a href=value>Extracting Values from <code>toml::value</code></a></a></li><li><a href=#creating-error-messages><a href=error_message>Creating Error Messages</a></a></li><li><a href=#serializing-toml-files><a href=serialize>Serializing TOML Files</a></a></li><li><a href=#configuring-types-of><a href=configure_types>Configuring Types of <code>toml::value</code></a></a></li><li><a href=#toml-literals><a href=literal>TOML Literals</a></a></li><li><a href=#toml-language-version><a href=toml_spec>TOML Language Version</a></a></li><li><a href=#toml-language-extensions><a href=extension>TOML Language Extensions</a></a></li></ul></li></ul></nav></div></aside></main></body></html>
|
||||
135
docs/features/index.xml
Normal file
135
docs/features/index.xml
Normal file
@@ -0,0 +1,135 @@
|
||||
<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"><channel><title>features on toml11</title><link>https://toruniina.github.io/toml11/docs/features/</link><description>Recent content in features on toml11</description><generator>Hugo</generator><language>en</language><atom:link href="https://toruniina.github.io/toml11/docs/features/index.xml" rel="self" type="application/rss+xml"/><item><title>parsing files</title><link>https://toruniina.github.io/toml11/docs/features/parsing_files/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://toruniina.github.io/toml11/docs/features/parsing_files/</guid><description><h1 id="parsing-files-and-strings">
|
||||
Parsing Files and Strings
|
||||
<a class="anchor" href="#parsing-files-and-strings">#</a>
|
||||
</h1>
|
||||
<p>In toml11, you can parse files, strings, and byte arrays using <code>toml::parse</code> or <code>toml::try_parse</code>.</p>
|
||||
<p>Upon success, these functions return a <code>toml::value</code>.
|
||||
Although the parsed file is always a table, the return type is not <code>toml::table</code>.
|
||||
This is because <code>toml::value</code> contains metadata about the file, whereas <code>toml::table</code> is merely an alias for <code>std::unordered_map&lt;std::string, toml::value&gt;</code>.
|
||||
To include metadata, a <code>toml::value</code> is returned instead of a <code>toml::table</code>.
|
||||
The <code>toml::value</code> corresponding to the root of the file will always hold a <code>table_type</code>.</p></description></item><item><title>getting values</title><link>https://toruniina.github.io/toml11/docs/features/value/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://toruniina.github.io/toml11/docs/features/value/</guid><description><h1 id="retrieving-values">
|
||||
Retrieving Values
|
||||
<a class="anchor" href="#retrieving-values">#</a>
|
||||
</h1>
|
||||
<p>This section explains how to access the values stored in <code>toml::value</code>.</p>
|
||||
<h2 id="accessing-values-using-member-functions">
|
||||
Accessing Values Using Member Functions
|
||||
<a class="anchor" href="#accessing-values-using-member-functions">#</a>
|
||||
</h2>
|
||||
<h3 id="is_something-and-as_something">
|
||||
<code>is_something</code> and <code>as_something</code>
|
||||
<a class="anchor" href="#is_something-and-as_something">#</a>
|
||||
</h3>
|
||||
<p><code>toml::value</code> has member functions like <code>is_boolean()</code> and <code>is_integer()</code> which allow you to check the type of the stored value.</p>
|
||||
<p>Additionally, it has member functions like <code>as_boolean()</code> and <code>as_integer()</code> that allow you to access the value of that type.</p>
|
||||
<p>For a complete list, refer to the <a href="https://toruniina.github.io/toml11/docs/reference/value/#is_xxx"><code>toml::value</code> reference</a>.</p></description></item><item><title>error message</title><link>https://toruniina.github.io/toml11/docs/features/error_message/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://toruniina.github.io/toml11/docs/features/error_message/</guid><description><h1 id="outputting-error-messages">
|
||||
Outputting Error Messages
|
||||
<a class="anchor" href="#outputting-error-messages">#</a>
|
||||
</h1>
|
||||
<p><code>toml11</code> provides error messages that include location information within the file when using functions like <code>toml::parse</code>, <code>toml::get&lt;T&gt;/find&lt;T&gt;</code>, and <code>as_integer()</code>, among others.</p>
|
||||
<p>For instance, if a syntax error in an integer is detected during parsing, an error message might look like this:</p>
|
||||
<pre tabindex="0"><code>[error] bad integer: `_` must be surrounded by digits
|
||||
--&gt; internal string at line 64 in file main.cpp
|
||||
|
|
||||
1 | a = 123__456
|
||||
| ^-- invalid underscore
|
||||
Hint: valid : -42, 1_000, 1_2_3_4_5, 0xC0FFEE, 0b0010, 0o755
|
||||
Hint: invalid: _42, 1__000, 0123
|
||||
</code></pre><p>Or, if a type different from the one actually stored is requested:</p></description></item><item><title>serializing values</title><link>https://toruniina.github.io/toml11/docs/features/serialize/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://toruniina.github.io/toml11/docs/features/serialize/</guid><description><h1 id="outputting-toml-files">
|
||||
Outputting TOML Files
|
||||
<a class="anchor" href="#outputting-toml-files">#</a>
|
||||
</h1>
|
||||
<p>Using <code>toml::format</code>, you can convert a <code>toml::value</code> to a string.</p>
|
||||
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-cpp" data-lang="cpp"><span style="display:flex;"><span><span style="color:#75715e">#include</span> <span style="color:#75715e">&lt;toml.hpp&gt;</span><span style="color:#75715e">
|
||||
</span></span></span><span style="display:flex;"><span><span style="color:#75715e">#include</span> <span style="color:#75715e">&lt;cassert&gt;</span><span style="color:#75715e">
|
||||
</span></span></span><span style="display:flex;"><span><span style="color:#75715e"></span>
|
||||
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">int</span> <span style="color:#a6e22e">main</span>()
|
||||
</span></span><span style="display:flex;"><span>{
|
||||
</span></span><span style="display:flex;"><span> <span style="color:#66d9ef">const</span> toml<span style="color:#f92672">::</span>value v(toml<span style="color:#f92672">::</span>table{
|
||||
</span></span><span style="display:flex;"><span> {<span style="color:#e6db74">&#34;a&#34;</span>, <span style="color:#ae81ff">42</span>},
|
||||
</span></span><span style="display:flex;"><span> {<span style="color:#e6db74">&#34;b&#34;</span>, <span style="color:#e6db74">&#34;foo&#34;</span>},
|
||||
</span></span><span style="display:flex;"><span> });
|
||||
</span></span><span style="display:flex;"><span> <span style="color:#66d9ef">const</span> std<span style="color:#f92672">::</span>string s <span style="color:#f92672">=</span> toml<span style="color:#f92672">::</span>format(v);
|
||||
</span></span><span style="display:flex;"><span>
|
||||
</span></span><span style="display:flex;"><span> <span style="color:#66d9ef">const</span> toml<span style="color:#f92672">::</span>value u <span style="color:#f92672">=</span> toml<span style="color:#f92672">::</span>parse_str(s);
|
||||
</span></span><span style="display:flex;"><span>
|
||||
</span></span><span style="display:flex;"><span> assert(u.at(<span style="color:#e6db74">&#34;a&#34;</span>).as_integer() <span style="color:#f92672">==</span> <span style="color:#ae81ff">42</span>);
|
||||
</span></span><span style="display:flex;"><span> assert(u.at(<span style="color:#e6db74">&#34;b&#34;</span>).as_string() <span style="color:#f92672">==</span> <span style="color:#e6db74">&#34;foo&#34;</span>);
|
||||
</span></span><span style="display:flex;"><span>
|
||||
</span></span><span style="display:flex;"><span> <span style="color:#66d9ef">return</span> <span style="color:#ae81ff">0</span>;
|
||||
</span></span><span style="display:flex;"><span>}
|
||||
</span></span></code></pre></div><p>If the <code>toml::value</code> contains a <code>table_type</code>, it is interpreted as the root table of the file.</p>
|
||||
<p>If a <code>toml::value</code> containing anything other than <code>table_type</code> is passed, only that value is formatted.</p></description></item><item><title>configuring types</title><link>https://toruniina.github.io/toml11/docs/features/configure_types/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://toruniina.github.io/toml11/docs/features/configure_types/</guid><description><h1 id="customizing-types">
|
||||
Customizing Types
|
||||
<a class="anchor" href="#customizing-types">#</a>
|
||||
</h1>
|
||||
<p>The <code>toml::value</code> class uses <code>std::int64_t</code> for <code>integer_type</code> and <code>std::unordered_map&lt;key_type, value_type&gt;</code> for <code>table_type</code>.</p>
|
||||
<p>However, in some cases, you may want to use <code>boost::multiprecision::int128_t</code> or <code>std::map</code>.</p>
|
||||
<p>To accommodate this, <code>toml::value</code> is implemented with template parameters that allow you to change the stored types.</p>
|
||||
<p>Just as <code>std::string</code> is actually an alias for <code>std::basic_string&lt;char, std::char_traits&lt;char&gt;, std::allocator&lt;char&gt;&gt;</code>, <code>toml::value</code> is an alias for <code>toml::basic_value&lt;toml::type_config&gt;</code>.</p>
|
||||
<p>Here, we will explain the types contained in <code>toml::type_config</code> and how to define a different <code>config</code> type.</p></description></item><item><title>toml literal</title><link>https://toruniina.github.io/toml11/docs/features/literal/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://toruniina.github.io/toml11/docs/features/literal/</guid><description><h1 id="_toml-literal">
|
||||
<code>_toml</code> Literal
|
||||
<a class="anchor" href="#_toml-literal">#</a>
|
||||
</h1>
|
||||
<p>With the <code>&quot;&quot;_toml</code> literal, you can format TOML files inline.</p>
|
||||
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-cpp" data-lang="cpp"><span style="display:flex;"><span><span style="color:#75715e">#include</span> <span style="color:#75715e">&lt;toml.hpp&gt;</span><span style="color:#75715e">
|
||||
</span></span></span><span style="display:flex;"><span><span style="color:#75715e"></span>
|
||||
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">int</span> <span style="color:#a6e22e">main</span>()
|
||||
</span></span><span style="display:flex;"><span>{
|
||||
</span></span><span style="display:flex;"><span> <span style="color:#66d9ef">using</span> <span style="color:#66d9ef">namespace</span> toml<span style="color:#f92672">::</span>literals<span style="color:#f92672">::</span>toml_literals;
|
||||
</span></span><span style="display:flex;"><span>
|
||||
</span></span><span style="display:flex;"><span> <span style="color:#66d9ef">const</span> <span style="color:#66d9ef">auto</span> v <span style="color:#f92672">=</span> <span style="color:#e6db74">&#34;a = 42&#34;</span>_toml;
|
||||
</span></span><span style="display:flex;"><span>
|
||||
</span></span><span style="display:flex;"><span> assert(v.at(<span style="color:#e6db74">&#34;a&#34;</span>).as_integer() <span style="color:#f92672">==</span> <span style="color:#ae81ff">42</span>);
|
||||
</span></span><span style="display:flex;"><span>
|
||||
</span></span><span style="display:flex;"><span> <span style="color:#66d9ef">return</span> <span style="color:#ae81ff">0</span>;
|
||||
</span></span><span style="display:flex;"><span>}
|
||||
</span></span></code></pre></div><p>When including line breaks, raw string literals come in handy.</p>
|
||||
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-cpp" data-lang="cpp"><span style="display:flex;"><span><span style="color:#75715e">#include</span> <span style="color:#75715e">&lt;toml.hpp&gt;</span><span style="color:#75715e">
|
||||
</span></span></span><span style="display:flex;"><span><span style="color:#75715e"></span>
|
||||
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">int</span> <span style="color:#a6e22e">main</span>()
|
||||
</span></span><span style="display:flex;"><span>{
|
||||
</span></span><span style="display:flex;"><span> <span style="color:#66d9ef">using</span> <span style="color:#66d9ef">namespace</span> toml<span style="color:#f92672">::</span>literals<span style="color:#f92672">::</span>toml_literals;
|
||||
</span></span><span style="display:flex;"><span>
|
||||
</span></span><span style="display:flex;"><span> <span style="color:#66d9ef">const</span> <span style="color:#66d9ef">auto</span> v <span style="color:#f92672">=</span> R<span style="color:#e6db74">&#34;(</span>
|
||||
</span></span><span style="display:flex;"><span> a <span style="color:#f92672">=</span> <span style="color:#ae81ff">42</span>
|
||||
</span></span><span style="display:flex;"><span> b <span style="color:#f92672">=</span> <span style="color:#e6db74">&#34;foo&#34;</span>
|
||||
</span></span><span style="display:flex;"><span> )<span style="color:#e6db74">&#34;_toml;</span>
|
||||
</span></span><span style="display:flex;"><span>
|
||||
</span></span><span style="display:flex;"><span> assert(v.at(<span style="color:#e6db74">&#34;a&#34;</span>).as_integer() <span style="color:#f92672">==</span> <span style="color:#ae81ff">42</span>);
|
||||
</span></span><span style="display:flex;"><span> assert(v.at(<span style="color:#e6db74">&#34;b&#34;</span>).as_string() <span style="color:#f92672">==</span> <span style="color:#e6db74">&#34;foo&#34;</span>);
|
||||
</span></span><span style="display:flex;"><span>
|
||||
</span></span><span style="display:flex;"><span> <span style="color:#66d9ef">return</span> <span style="color:#ae81ff">0</span>;
|
||||
</span></span><span style="display:flex;"><span>}
|
||||
</span></span></code></pre></div><p>If a value is written on its own, that value is returned.</p></description></item><item><title>toml spec</title><link>https://toruniina.github.io/toml11/docs/features/toml_spec/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://toruniina.github.io/toml11/docs/features/toml_spec/</guid><description><h1 id="toml-language-version">
|
||||
TOML Language Version
|
||||
<a class="anchor" href="#toml-language-version">#</a>
|
||||
</h1>
|
||||
<p>You can specify the version of the TOML language and individual feature flags to use with <code>toml::parse</code> or <code>toml::format</code> through <a href="https://toruniina.github.io/toml11/docs/reference/spec/#tomlspec"><code>toml::spec</code></a>.</p>
|
||||
<h2 id="specifying-toml-version">
|
||||
Specifying TOML Version
|
||||
<a class="anchor" href="#specifying-toml-version">#</a>
|
||||
</h2>
|
||||
<p>You can construct a <a href="https://toruniina.github.io/toml11/docs/reference/spec/#tomlspec"><code>toml::spec</code></a> from <a href="https://toruniina.github.io/toml11/docs/reference/spec/#tomlsemantic_version"><code>toml::semantic_version</code></a>.</p>
|
||||
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-cpp" data-lang="cpp"><span style="display:flex;"><span><span style="color:#75715e">#include</span> <span style="color:#75715e">&lt;toml.hpp&gt;</span><span style="color:#75715e">
|
||||
</span></span></span><span style="display:flex;"><span><span style="color:#75715e"></span>
|
||||
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">int</span> <span style="color:#a6e22e">main</span>()
|
||||
</span></span><span style="display:flex;"><span>{
|
||||
</span></span><span style="display:flex;"><span> toml<span style="color:#f92672">::</span>spec spec(toml<span style="color:#f92672">::</span>semantic_version(<span style="color:#ae81ff">1</span>, <span style="color:#ae81ff">1</span>, <span style="color:#ae81ff">0</span>));
|
||||
</span></span><span style="display:flex;"><span> <span style="color:#66d9ef">return</span> <span style="color:#ae81ff">0</span>;
|
||||
</span></span><span style="display:flex;"><span>}
|
||||
</span></span></code></pre></div><p>However, to make this shorter, the <code>toml::spec::v()</code> function is provided.</p>
|
||||
<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-cpp" data-lang="cpp"><span style="display:flex;"><span><span style="color:#75715e">#include</span> <span style="color:#75715e">&lt;toml.hpp&gt;</span><span style="color:#75715e">
|
||||
</span></span></span><span style="display:flex;"><span><span style="color:#75715e"></span>
|
||||
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">int</span> <span style="color:#a6e22e">main</span>()
|
||||
</span></span><span style="display:flex;"><span>{
|
||||
</span></span><span style="display:flex;"><span> toml<span style="color:#f92672">::</span>spec spec <span style="color:#f92672">=</span> toml<span style="color:#f92672">::</span>spec<span style="color:#f92672">::</span>v(<span style="color:#ae81ff">1</span>, <span style="color:#ae81ff">1</span>, <span style="color:#ae81ff">0</span>);
|
||||
</span></span><span style="display:flex;"><span> <span style="color:#66d9ef">return</span> <span style="color:#ae81ff">0</span>;
|
||||
</span></span><span style="display:flex;"><span>}
|
||||
</span></span></code></pre></div><p>If not specified explicitly, <code>toml::spec::default_version()</code> is used to construct with default values.</p></description></item><item><title>extension</title><link>https://toruniina.github.io/toml11/docs/features/extension/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://toruniina.github.io/toml11/docs/features/extension/</guid><description><h1 id="toml-language-extensions">
|
||||
TOML Language Extensions
|
||||
<a class="anchor" href="#toml-language-extensions">#</a>
|
||||
</h1>
|
||||
<p>The TOML language is currently at version v1.0.0, but several new features have been discussed and merged, with ongoing discussions for v1.1.0.</p>
|
||||
<p>Among the proposed features, some were deemed to have limited use cases, some faced implementation challenges in their proposed form, and others were not adopted at all.</p>
|
||||
<p>In toml11, we have experimentally implemented a selection of these features. Please note that these features are supported in toml11 but are not supported by other parsers and are unlikely to be supported in the future.</p></description></item></channel></rss>
|
||||
107
docs/features/literal/index.html
Normal file
107
docs/features/literal/index.html
Normal file
@@ -0,0 +1,107 @@
|
||||
<!doctype html><html lang=en dir=ltr><head><meta charset=UTF-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content='
|
||||
_toml Literal
|
||||
#
|
||||
|
||||
With the ""_toml literal, you can format TOML files inline.
|
||||
#include <toml.hpp>
|
||||
|
||||
int main()
|
||||
{
|
||||
using namespace toml::literals::toml_literals;
|
||||
|
||||
const auto v = "a = 42"_toml;
|
||||
|
||||
assert(v.at("a").as_integer() == 42);
|
||||
|
||||
return 0;
|
||||
}
|
||||
When including line breaks, raw string literals come in handy.
|
||||
#include <toml.hpp>
|
||||
|
||||
int main()
|
||||
{
|
||||
using namespace toml::literals::toml_literals;
|
||||
|
||||
const auto v = R"(
|
||||
a = 42
|
||||
b = "foo"
|
||||
)"_toml;
|
||||
|
||||
assert(v.at("a").as_integer() == 42);
|
||||
assert(v.at("b").as_string() == "foo");
|
||||
|
||||
return 0;
|
||||
}
|
||||
If a value is written on its own, that value is returned.'><meta name=theme-color media="(prefers-color-scheme: light)" content="#ffffff"><meta name=theme-color media="(prefers-color-scheme: dark)" content="#343a40"><meta name=color-scheme content="light dark"><meta property="og:url" content="https://toruniina.github.io/toml11/docs/features/literal/"><meta property="og:site_name" content="toml11"><meta property="og:title" content="toml literal"><meta property="og:description" content='_toml Literal # With the ""_toml literal, you can format TOML files inline.
|
||||
#include <toml.hpp> int main() { using namespace toml::literals::toml_literals; const auto v = "a = 42"_toml; assert(v.at("a").as_integer() == 42); return 0; } When including line breaks, raw string literals come in handy.
|
||||
#include <toml.hpp> int main() { using namespace toml::literals::toml_literals; const auto v = R"( a = 42 b = "foo" )"_toml; assert(v.at("a").as_integer() == 42); assert(v.at("b").as_string() == "foo"); return 0; } If a value is written on its own, that value is returned.'><meta property="og:locale" content="en"><meta property="og:type" content="article"><meta property="article:section" content="docs"><title>toml literal | toml11</title>
|
||||
<link rel=manifest href=/toml11/manifest.json><link rel=icon href=/toml11/favicon.png><link rel=canonical href=https://toruniina.github.io/toml11/docs/features/literal/><link rel=alternate hreflang=ja href=https://toruniina.github.io/toml11/ja/docs/features/literal/ title="toml literal"><link rel=stylesheet href=/toml11/book.min.ddac3efe7ea4c1007ff53e5a8fd67f12517e5d2e99984d8c67a18668f7ecaa03.css integrity="sha256-3aw+/n6kwQB/9T5aj9Z/ElF+XS6ZmE2MZ6GGaPfsqgM=" crossorigin=anonymous><script defer src=/toml11/fuse.min.js></script><script defer src=/toml11/en.search.min.db4a558804ac41f081539588cec8e4a415587801da466728166bb5341dd62411.js integrity="sha256-20pViASsQfCBU5WIzsjkpBVYeAHaRmcoFmu1NB3WJBE=" crossorigin=anonymous></script></head><body dir=ltr><input type=checkbox class="hidden toggle" id=menu-control>
|
||||
<input type=checkbox class="hidden toggle" id=toc-control><main class="container flex"><aside class=book-menu><div class=book-menu-content><nav><h2 class=book-brand><a class="flex align-center" href=/toml11/><span>toml11</span></a></h2><div class="book-search hidden"><input type=text id=book-search-input placeholder=Search aria-label=Search maxlength=64 data-hotkeys=s/><div class="book-search-spinner hidden"></div><ul id=book-search-results></ul></div><script>document.querySelector(".book-search").classList.remove("hidden")</script><ul class=book-languages><li><input type=checkbox id=languages class=toggle>
|
||||
<label for=languages class="flex justify-between"><a role=button class="flex align-center"><img src=/toml11/svg/translate.svg class=book-icon alt=Languages>
|
||||
English</a></label><ul><li><a href=https://toruniina.github.io/toml11/ja/docs/features/literal/>日本語</a></li></ul></li></ul><ul><li><a href=/toml11/docs/installation/>installation</a><ul></ul></li><li><input type=checkbox id=section-291123c850af98d8b815ccdbb4c33657 class=toggle checked>
|
||||
<label for=section-291123c850af98d8b815ccdbb4c33657 class="flex justify-between"><a href=/toml11/docs/features/>features</a></label><ul><li><a href=/toml11/docs/features/parsing_files/>parsing files</a></li><li><a href=/toml11/docs/features/value/>getting values</a></li><li><a href=/toml11/docs/features/error_message/>error message</a></li><li><a href=/toml11/docs/features/serialize/>serializing values</a></li><li><a href=/toml11/docs/features/configure_types/>configuring types</a></li><li><a href=/toml11/docs/features/literal/ class=active>toml literal</a></li><li><a href=/toml11/docs/features/toml_spec/>toml spec</a></li><li><a href=/toml11/docs/features/extension/>extension</a></li></ul></li><li><input type=checkbox id=section-e2e812e55021b82e114feaae98f1a02e class=toggle>
|
||||
<label for=section-e2e812e55021b82e114feaae98f1a02e class="flex justify-between"><a href=/toml11/docs/reference/>reference</a></label><ul><li><a href=/toml11/docs/reference/color/>color.hpp</a></li><li><a href=/toml11/docs/reference/comments/>comments.hpp</a></li><li><a href=/toml11/docs/reference/conversion/>conversion.hpp</a></li><li><a href=/toml11/docs/reference/datetime/>datetime.hpp</a></li><li><a href=/toml11/docs/reference/error_info/>error_info.hpp</a></li><li><a href=/toml11/docs/reference/exception/>exception.hpp</a></li><li><a href=/toml11/docs/reference/find/>find.hpp</a></li><li><a href=/toml11/docs/reference/format/>format.hpp</a></li><li><a href=/toml11/docs/reference/from/>from.hpp</a></li><li><a href=/toml11/docs/reference/get/>get.hpp</a></li><li><a href=/toml11/docs/reference/into/>into.hpp</a></li><li><a href=/toml11/docs/reference/literal/>literal.hpp</a></li><li><a href=/toml11/docs/reference/ordered_map/>ordered_map.hpp</a></li><li><a href=/toml11/docs/reference/parser/>parser.hpp</a></li><li><a href=/toml11/docs/reference/result/>result.hpp</a></li><li><a href=/toml11/docs/reference/serializer/>serializer.hpp</a></li><li><a href=/toml11/docs/reference/source_location/>source_location.hpp</a></li><li><a href=/toml11/docs/reference/spec/>spec.hpp</a></li><li><a href=/toml11/docs/reference/toml_fwd/>toml_fwd.hpp</a></li><li><a href=/toml11/docs/reference/toml/>toml.hpp</a></li><li><a href=/toml11/docs/reference/types/>types.hpp</a></li><li><a href=/toml11/docs/reference/value_t/>value_t.hpp</a></li><li><a href=/toml11/docs/reference/value/>value.hpp</a></li><li><a href=/toml11/docs/reference/version/>version.hpp</a></li><li><a href=/toml11/docs/reference/visit/>visit.hpp</a></li></ul></li><li><a href=/toml11/docs/changelog/>changelog</a><ul></ul></li></ul><ul><li><a href=https://github.com/ToruNiina/toml11 target=_blank rel=noopener>GitHub</a></li></ul></nav><script>(function(){var e=document.querySelector("aside .book-menu-content");addEventListener("beforeunload",function(){localStorage.setItem("menu.scrollTop",e.scrollTop)}),e.scrollTop=localStorage.getItem("menu.scrollTop")})()</script></div></aside><div class=book-page><header class=book-header><div class="flex align-center justify-between"><label for=menu-control><img src=/toml11/svg/menu.svg class=book-icon alt=Menu>
|
||||
</label><strong>toml literal</strong>
|
||||
<label for=toc-control><img src=/toml11/svg/toc.svg class=book-icon alt="Table of Contents"></label></div><aside class="hidden clearfix"><nav id=TableOfContents><ul><li><a href=#_toml-literal><code>_toml</code> Literal</a></li></ul></nav></aside></header><article class="markdown book-article"><h1 id=_toml-literal><code>_toml</code> Literal
|
||||
<a class=anchor href=#_toml-literal>#</a></h1><p>With the <code>""_toml</code> literal, you can format TOML files inline.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><toml.hpp></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>int</span> <span style=color:#a6e22e>main</span>()
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> <span style=color:#66d9ef>namespace</span> toml<span style=color:#f92672>::</span>literals<span style=color:#f92672>::</span>toml_literals;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> v <span style=color:#f92672>=</span> <span style=color:#e6db74>"a = 42"</span>_toml;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> assert(v.at(<span style=color:#e6db74>"a"</span>).as_integer() <span style=color:#f92672>==</span> <span style=color:#ae81ff>42</span>);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> <span style=color:#ae81ff>0</span>;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><p>When including line breaks, raw string literals come in handy.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><toml.hpp></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>int</span> <span style=color:#a6e22e>main</span>()
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> <span style=color:#66d9ef>namespace</span> toml<span style=color:#f92672>::</span>literals<span style=color:#f92672>::</span>toml_literals;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> v <span style=color:#f92672>=</span> R<span style=color:#e6db74>"(</span>
|
||||
</span></span><span style=display:flex><span> a <span style=color:#f92672>=</span> <span style=color:#ae81ff>42</span>
|
||||
</span></span><span style=display:flex><span> b <span style=color:#f92672>=</span> <span style=color:#e6db74>"foo"</span>
|
||||
</span></span><span style=display:flex><span> )<span style=color:#e6db74>"_toml;</span>
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> assert(v.at(<span style=color:#e6db74>"a"</span>).as_integer() <span style=color:#f92672>==</span> <span style=color:#ae81ff>42</span>);
|
||||
</span></span><span style=display:flex><span> assert(v.at(<span style=color:#e6db74>"b"</span>).as_string() <span style=color:#f92672>==</span> <span style=color:#e6db74>"foo"</span>);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> <span style=color:#ae81ff>0</span>;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><p>If a value is written on its own, that value is returned.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><toml.hpp></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>int</span> <span style=color:#a6e22e>main</span>()
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> <span style=color:#66d9ef>namespace</span> toml<span style=color:#f92672>::</span>literals<span style=color:#f92672>::</span>toml_literals;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> <span style=color:#e6db74>"42"</span>_toml;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> b <span style=color:#f92672>=</span> <span style=color:#e6db74>"12:34:56"</span>_toml;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> assert(a.as_integer() <span style=color:#f92672>==</span> <span style=color:#ae81ff>42</span>);
|
||||
</span></span><span style=display:flex><span> assert(b.as_local_time().hour <span style=color:#f92672>==</span> <span style=color:#ae81ff>12</span>);
|
||||
</span></span><span style=display:flex><span> assert(b.as_local_time().minute <span style=color:#f92672>==</span> <span style=color:#ae81ff>34</span>);
|
||||
</span></span><span style=display:flex><span> assert(b.as_local_time().second <span style=color:#f92672>==</span> <span style=color:#ae81ff>56</span>);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> <span style=color:#ae81ff>0</span>;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><p>TOML allows keys consisting solely of numbers. Therefore, <code>[1]</code> is a valid table name.</p><p>When there’s ambiguity between table definitions and arrays, table definitions take precedence.</p><p>To interpret as an array, please use a trailing comma.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><toml.hpp></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>int</span> <span style=color:#a6e22e>main</span>()
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>using</span> <span style=color:#66d9ef>namespace</span> toml<span style=color:#f92672>::</span>literals<span style=color:#f92672>::</span>toml_literals;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> t <span style=color:#f92672>=</span> <span style=color:#e6db74>"[1]"</span>_toml; <span style=color:#75715e>// {1 = {}}
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span> <span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> <span style=color:#e6db74>"[1,]"</span>_toml; <span style=color:#75715e>// [1,]
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span> assert(t.is_table());
|
||||
</span></span><span style=display:flex><span> assert(t.at(<span style=color:#e6db74>"1"</span>).is_table());
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> assert(a.is_array());
|
||||
</span></span><span style=display:flex><span> assert(a.at(<span style=color:#ae81ff>0</span>).as_integer() <span style=color:#f92672>==</span> <span style=color:#ae81ff>1</span>);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> <span style=color:#ae81ff>0</span>;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div></article><footer class=book-footer><div class="flex flex-wrap justify-between"></div><script>(function(){function e(e){const t=window.getSelection(),n=document.createRange();n.selectNodeContents(e),t.removeAllRanges(),t.addRange(n)}document.querySelectorAll("pre code").forEach(t=>{t.addEventListener("click",function(){if(window.getSelection().toString())return;e(t.parentElement),navigator.clipboard&&navigator.clipboard.writeText(t.parentElement.textContent)})})})()</script></footer><label for=menu-control class="hidden book-menu-overlay"></label></div><aside class=book-toc><div class=book-toc-content><nav id=TableOfContents><ul><li><a href=#_toml-literal><code>_toml</code> Literal</a></li></ul></nav></div></aside></main></body></html>
|
||||
144
docs/features/parsing_files/index.html
Normal file
144
docs/features/parsing_files/index.html
Normal file
@@ -0,0 +1,144 @@
|
||||
<!doctype html><html lang=en dir=ltr><head><meta charset=UTF-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="
|
||||
Parsing Files and Strings
|
||||
#
|
||||
|
||||
In toml11, you can parse files, strings, and byte arrays using toml::parse or toml::try_parse.
|
||||
Upon success, these functions return a toml::value.
|
||||
Although the parsed file is always a table, the return type is not toml::table.
|
||||
This is because toml::value contains metadata about the file, whereas toml::table is merely an alias for std::unordered_map<std::string, toml::value>.
|
||||
To include metadata, a toml::value is returned instead of a toml::table.
|
||||
The toml::value corresponding to the root of the file will always hold a table_type."><meta name=theme-color media="(prefers-color-scheme: light)" content="#ffffff"><meta name=theme-color media="(prefers-color-scheme: dark)" content="#343a40"><meta name=color-scheme content="light dark"><meta property="og:url" content="https://toruniina.github.io/toml11/docs/features/parsing_files/"><meta property="og:site_name" content="toml11"><meta property="og:title" content="parsing files"><meta property="og:description" content="Parsing Files and Strings # In toml11, you can parse files, strings, and byte arrays using toml::parse or toml::try_parse.
|
||||
Upon success, these functions return a toml::value. Although the parsed file is always a table, the return type is not toml::table. This is because toml::value contains metadata about the file, whereas toml::table is merely an alias for std::unordered_map<std::string, toml::value>. To include metadata, a toml::value is returned instead of a toml::table. The toml::value corresponding to the root of the file will always hold a table_type."><meta property="og:locale" content="en"><meta property="og:type" content="article"><meta property="article:section" content="docs"><title>parsing files | toml11</title>
|
||||
<link rel=manifest href=/toml11/manifest.json><link rel=icon href=/toml11/favicon.png><link rel=canonical href=https://toruniina.github.io/toml11/docs/features/parsing_files/><link rel=alternate hreflang=ja href=https://toruniina.github.io/toml11/ja/docs/features/parsing_files/ title="parsing files"><link rel=stylesheet href=/toml11/book.min.ddac3efe7ea4c1007ff53e5a8fd67f12517e5d2e99984d8c67a18668f7ecaa03.css integrity="sha256-3aw+/n6kwQB/9T5aj9Z/ElF+XS6ZmE2MZ6GGaPfsqgM=" crossorigin=anonymous><script defer src=/toml11/fuse.min.js></script><script defer src=/toml11/en.search.min.db4a558804ac41f081539588cec8e4a415587801da466728166bb5341dd62411.js integrity="sha256-20pViASsQfCBU5WIzsjkpBVYeAHaRmcoFmu1NB3WJBE=" crossorigin=anonymous></script></head><body dir=ltr><input type=checkbox class="hidden toggle" id=menu-control>
|
||||
<input type=checkbox class="hidden toggle" id=toc-control><main class="container flex"><aside class=book-menu><div class=book-menu-content><nav><h2 class=book-brand><a class="flex align-center" href=/toml11/><span>toml11</span></a></h2><div class="book-search hidden"><input type=text id=book-search-input placeholder=Search aria-label=Search maxlength=64 data-hotkeys=s/><div class="book-search-spinner hidden"></div><ul id=book-search-results></ul></div><script>document.querySelector(".book-search").classList.remove("hidden")</script><ul class=book-languages><li><input type=checkbox id=languages class=toggle>
|
||||
<label for=languages class="flex justify-between"><a role=button class="flex align-center"><img src=/toml11/svg/translate.svg class=book-icon alt=Languages>
|
||||
English</a></label><ul><li><a href=https://toruniina.github.io/toml11/ja/docs/features/parsing_files/>日本語</a></li></ul></li></ul><ul><li><a href=/toml11/docs/installation/>installation</a><ul></ul></li><li><input type=checkbox id=section-291123c850af98d8b815ccdbb4c33657 class=toggle checked>
|
||||
<label for=section-291123c850af98d8b815ccdbb4c33657 class="flex justify-between"><a href=/toml11/docs/features/>features</a></label><ul><li><a href=/toml11/docs/features/parsing_files/ class=active>parsing files</a></li><li><a href=/toml11/docs/features/value/>getting values</a></li><li><a href=/toml11/docs/features/error_message/>error message</a></li><li><a href=/toml11/docs/features/serialize/>serializing values</a></li><li><a href=/toml11/docs/features/configure_types/>configuring types</a></li><li><a href=/toml11/docs/features/literal/>toml literal</a></li><li><a href=/toml11/docs/features/toml_spec/>toml spec</a></li><li><a href=/toml11/docs/features/extension/>extension</a></li></ul></li><li><input type=checkbox id=section-e2e812e55021b82e114feaae98f1a02e class=toggle>
|
||||
<label for=section-e2e812e55021b82e114feaae98f1a02e class="flex justify-between"><a href=/toml11/docs/reference/>reference</a></label><ul><li><a href=/toml11/docs/reference/color/>color.hpp</a></li><li><a href=/toml11/docs/reference/comments/>comments.hpp</a></li><li><a href=/toml11/docs/reference/conversion/>conversion.hpp</a></li><li><a href=/toml11/docs/reference/datetime/>datetime.hpp</a></li><li><a href=/toml11/docs/reference/error_info/>error_info.hpp</a></li><li><a href=/toml11/docs/reference/exception/>exception.hpp</a></li><li><a href=/toml11/docs/reference/find/>find.hpp</a></li><li><a href=/toml11/docs/reference/format/>format.hpp</a></li><li><a href=/toml11/docs/reference/from/>from.hpp</a></li><li><a href=/toml11/docs/reference/get/>get.hpp</a></li><li><a href=/toml11/docs/reference/into/>into.hpp</a></li><li><a href=/toml11/docs/reference/literal/>literal.hpp</a></li><li><a href=/toml11/docs/reference/ordered_map/>ordered_map.hpp</a></li><li><a href=/toml11/docs/reference/parser/>parser.hpp</a></li><li><a href=/toml11/docs/reference/result/>result.hpp</a></li><li><a href=/toml11/docs/reference/serializer/>serializer.hpp</a></li><li><a href=/toml11/docs/reference/source_location/>source_location.hpp</a></li><li><a href=/toml11/docs/reference/spec/>spec.hpp</a></li><li><a href=/toml11/docs/reference/toml_fwd/>toml_fwd.hpp</a></li><li><a href=/toml11/docs/reference/toml/>toml.hpp</a></li><li><a href=/toml11/docs/reference/types/>types.hpp</a></li><li><a href=/toml11/docs/reference/value_t/>value_t.hpp</a></li><li><a href=/toml11/docs/reference/value/>value.hpp</a></li><li><a href=/toml11/docs/reference/version/>version.hpp</a></li><li><a href=/toml11/docs/reference/visit/>visit.hpp</a></li></ul></li><li><a href=/toml11/docs/changelog/>changelog</a><ul></ul></li></ul><ul><li><a href=https://github.com/ToruNiina/toml11 target=_blank rel=noopener>GitHub</a></li></ul></nav><script>(function(){var e=document.querySelector("aside .book-menu-content");addEventListener("beforeunload",function(){localStorage.setItem("menu.scrollTop",e.scrollTop)}),e.scrollTop=localStorage.getItem("menu.scrollTop")})()</script></div></aside><div class=book-page><header class=book-header><div class="flex align-center justify-between"><label for=menu-control><img src=/toml11/svg/menu.svg class=book-icon alt=Menu>
|
||||
</label><strong>parsing files</strong>
|
||||
<label for=toc-control><img src=/toml11/svg/toc.svg class=book-icon alt="Table of Contents"></label></div><aside class="hidden clearfix"><nav id=TableOfContents><ul><li><a href=#parsing-files-and-strings>Parsing Files and Strings</a><ul><li><a href=#parsing-files>Parsing Files</a><ul><li><a href=#tomlparse><code>toml::parse</code></a></li><li><a href=#tomltry_parse><code>toml::try_parse</code></a></li></ul></li><li><a href=#parsing-strings>Parsing Strings</a><ul><li><a href=#tomlparse_str><code>toml::parse_str</code></a></li><li><a href=#tomltry_parse_str><code>toml::try_parse_str</code></a></li></ul></li><li><a href=#parsing-byte-arrays>Parsing Byte Arrays</a><ul><li><a href=#tomlparsestdvectorunsigned-char><code>toml::parse(std::vector<unsigned char>)</code></a></li><li><a href=#tomltry_parsestdvectorunsigned-char><code>toml::try_parse(std::vector<unsigned char>)</code></a></li></ul></li></ul></li></ul></nav></aside></header><article class="markdown book-article"><h1 id=parsing-files-and-strings>Parsing Files and Strings
|
||||
<a class=anchor href=#parsing-files-and-strings>#</a></h1><p>In toml11, you can parse files, strings, and byte arrays using <code>toml::parse</code> or <code>toml::try_parse</code>.</p><p>Upon success, these functions return a <code>toml::value</code>.
|
||||
Although the parsed file is always a table, the return type is not <code>toml::table</code>.
|
||||
This is because <code>toml::value</code> contains metadata about the file, whereas <code>toml::table</code> is merely an alias for <code>std::unordered_map<std::string, toml::value></code>.
|
||||
To include metadata, a <code>toml::value</code> is returned instead of a <code>toml::table</code>.
|
||||
The <code>toml::value</code> corresponding to the root of the file will always hold a <code>table_type</code>.</p><h2 id=parsing-files>Parsing Files
|
||||
<a class=anchor href=#parsing-files>#</a></h2><p>To parse files, use either
|
||||
<a href=https://toruniina.github.io/toml11/docs/reference/parser/#parse><code>toml::parse</code></a>
|
||||
or
|
||||
<a href=https://toruniina.github.io/toml11/docs/reference/parser/#try_parse><code>toml::try_parse</code></a>.</p><h3 id=tomlparse><code>toml::parse</code>
|
||||
<a class=anchor href=#tomlparse>#</a></h3><h4 id=specifying-the-filename-with-stdstring>Specifying the Filename with <code>std::string</code>
|
||||
<a class=anchor href=#specifying-the-filename-with-stdstring>#</a></h4><p><a href=https://toruniina.github.io/toml11/docs/reference/parser/#parse><code>toml::parse</code></a>
|
||||
accepts a filename as a string, opens the file, and parses it.</p><p>The following sample code parses a file named <code>input.toml</code>, extracts the <code>title</code> variable as a string, and prints it.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><toml.hpp></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><iostream></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>int</span> <span style=color:#a6e22e>main</span>()
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value input <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse(<span style=color:#e6db74>"input.toml"</span>);
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> input.at(<span style=color:#e6db74>"title"</span>).as_string() <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> <span style=color:#ae81ff>0</span>;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><h4 id=specifying-a-file-with-stdfilesystempath>Specifying a File with <code>std::filesystem::path</code>
|
||||
<a class=anchor href=#specifying-a-file-with-stdfilesystempath>#</a></h4><p><a href=https://toruniina.github.io/toml11/docs/reference/parser/#parse><code>toml::parse</code></a> can accept a <code>std::filesystem::path</code>.</p><p>This requires C++17 or later, as it relies on the <code><filesystem></code> support.</p><h4 id=specifying-an-input-stream-with-stdistream>Specifying an Input Stream with <code>std::istream</code>
|
||||
<a class=anchor href=#specifying-an-input-stream-with-stdistream>#</a></h4><p><a href=https://toruniina.github.io/toml11/docs/reference/parser/#parse><code>toml::parse</code></a> can also accept an <code>std::istream</code>.</p><p>Open a stream in binary mode by passing <code>std::ios::binary</code> to avoid inconsistency between the file size and the number of characters due to automatic conversion of newline characters by the standard library.</p><p>Without the filename information, error messages will display <code>"unknown file"</code>. To avoid this, you can pass the filename as a <code>std::string</code> in the second argument when using <code>std::istream</code>.</p><p>You can use streams other than <code>std::ifstream</code>, such as <code>std::istringstream</code>. Note that the entire content is readable at the time of the call.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><toml.hpp></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><iostream></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>int</span> <span style=color:#a6e22e>main</span>()
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string filename(<span style=color:#e6db74>"input.toml"</span>);
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>ifstream ifs(filename);
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value input <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse(ifs, filename);
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> input.at(<span style=color:#e6db74>"title"</span>).as_string() <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> <span style=color:#ae81ff>0</span>;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><h4 id=specifying-a-file-with-file>Specifying a File with <code>FILE*</code>
|
||||
<a class=anchor href=#specifying-a-file-with-file>#</a></h4><p><a href=https://toruniina.github.io/toml11/docs/reference/parser/#parse><code>toml::parse</code></a> can also accept a <code>FILE*</code>.</p><p>Open a stream in binary mode by passing <code>"rb"</code> to avoid inconsistency between the file size and the number of characters due to automatic conversion of newline characters by the standard library.</p><p>As with <code>std::istream</code>, you need to provide the filename as a string in the second argument.</p><p>When passing a <code>FILE*</code>, if the file read fails, <code>errno</code> will be reported.</p><h4 id=error-handling>Error Handling
|
||||
<a class=anchor href=#error-handling>#</a></h4><p><a href=https://toruniina.github.io/toml11/docs/reference/parser/#parse><code>toml::parse</code></a> throws a <a href=https://toruniina.github.io/toml11/docs/reference/parser/#syntax_error><code>toml::syntax_error</code></a> if it encounters a syntax error.</p><p><a href=https://toruniina.github.io/toml11/docs/reference/parser/#syntax_error><code>toml::syntax_error</code></a> is derived from <a href=https://toruniina.github.io/toml11/docs/reference/exception/><code>toml::exception</code></a>, which in turn is derived from <code>std::exception</code>.</p><p>Therefore, you can use the <code>what()</code> member function to retrieve the error message from a <a href=https://toruniina.github.io/toml11/docs/reference/parser/#syntax_error><code>toml::syntax_error</code></a>.</p><p>Additionally, <a href=https://toruniina.github.io/toml11/docs/reference/parser/#syntax_error><code>toml::syntax_error</code></a> contains a <a href=https://toruniina.github.io/toml11/docs/reference/error_info/><code>std::vector<toml::error_info></code></a>, which can be accessed using the <code>errors()</code> member function.</p><p><code>toml::parse</code> attempts to recover from minor errors and report multiple errors whenever possible. While it can often recover from simple errors like number format issues, errors within arrays or tables might not be recoverable and may lead to multiple similar error reports. If you find the error messages redundant, you can use only the <code>front()</code> of the <code>std::vector<toml::error_info></code> to get a message about the most critical issue.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><toml.hpp></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>int</span> <span style=color:#a6e22e>main</span>()
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>try</span> {
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value input <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse(<span style=color:#e6db74>"input.toml"</span>);
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> input.at(<span style=color:#e6db74>"title"</span>).as_string() <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span><span style=display:flex><span> } <span style=color:#66d9ef>catch</span>(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>syntax_error<span style=color:#f92672>&</span> err) {
|
||||
</span></span><span style=display:flex><span> <span style=color:#75715e>// report all the errors
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span> std<span style=color:#f92672>::</span>cerr <span style=color:#f92672><<</span> err.what() <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#75715e>// report the first error only
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span> std<span style=color:#f92672>::</span>cerr <span style=color:#f92672><<</span> err.errors().front() <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span><span style=display:flex><span> }
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><h3 id=tomltry_parse><code>toml::try_parse</code>
|
||||
<a class=anchor href=#tomltry_parse>#</a></h3><p>While <code>toml::parse</code> throws an exception on failure, <code>toml::try_parse</code> does not throw exceptions when it fails.</p><p>Instead, its return type is <a href=https://toruniina.github.io/toml11/docs/reference/result/#result><code>toml::result<toml::value, std::vector<toml::error_info>></code></a>.</p><p>The <a href=https://toruniina.github.io/toml11/docs/reference/result/#result><code>result</code></a> type holds either a success value or a failure value, similar to Rust’s <code>Result</code> or Haskell’s <code>Either</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><toml.hpp></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>int</span> <span style=color:#a6e22e>main</span>()
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> parse_result <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>try_parse(<span style=color:#e6db74>"input.toml"</span>);
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>if</span>(parse_result.is_ok())
|
||||
</span></span><span style=display:flex><span> {
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> parse_result.unwrap().at(<span style=color:#e6db74>"title"</span>).as_string() <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span><span style=display:flex><span> }
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>else</span>
|
||||
</span></span><span style=display:flex><span> {
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cerr <span style=color:#f92672><<</span> parse_result.unwrap_err().at(<span style=color:#ae81ff>0</span>) <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span><span style=display:flex><span> }
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> <span style=color:#ae81ff>0</span>;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><p>To check which value the <a href=https://toruniina.github.io/toml11/docs/reference/result/#result><code>result</code></a> type holds, use the <code>is_ok()</code> and <code>is_err()</code> functions. The success or failure value can be retrieved using <code>unwrap()</code> and <code>unwrap_err()</code>, respectively. If <code>unwrap</code> fails, it throws a <code>bad_result_access</code> exception. Using the <code>as_ok()</code> and <code>as_err()</code> functions does not throw exceptions on failure, but results in undefined behavior.</p><blockquote class="book-hint warning"><p>Although <code>try_parse</code> does not throw <code>syntax_error</code> or <code>file_io_error</code>, it returns the same <code>toml::error_info</code> as the failure type in the <code>result</code>. However, it is not entirely exception-free.</p><p>If an internal standard library error occurs, such as <code>std::bad_alloc</code> when a <code>vector</code> fails to allocate memory, <code>toml::try_parse</code> does not catch this and will let it propagate. Thus, exceptions originating from the standard library may still be thrown.</p></blockquote><h2 id=parsing-strings>Parsing Strings
|
||||
<a class=anchor href=#parsing-strings>#</a></h2><h3 id=tomlparse_str><code>toml::parse_str</code>
|
||||
<a class=anchor href=#tomlparse_str>#</a></h3><p><a href=https://toruniina.github.io/toml11/docs/reference/parser/#parse_str><code>toml::parse_str</code></a> accepts the string to be parsed directly, instead of a filename.</p><p>For the part of the error message that corresponds to the TOML file’s name, if the <code>std::source_location</code> equivalent compiler extension is available, the name and line number of the C++ file that called <code>parse_str</code> will be used instead.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><toml.hpp></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><iostream></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>int</span> <span style=color:#a6e22e>main</span>()
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value input <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse_str(<span style=color:#e6db74>"title = </span><span style=color:#ae81ff>\"</span><span style=color:#e6db74>parse_str</span><span style=color:#ae81ff>\"</span><span style=color:#e6db74>"</span>);
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> input.at(<span style=color:#e6db74>"title"</span>).as_string() <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> <span style=color:#ae81ff>0</span>;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><h3 id=tomltry_parse_str><code>toml::try_parse_str</code>
|
||||
<a class=anchor href=#tomltry_parse_str>#</a></h3><p><a href=https://toruniina.github.io/toml11/docs/reference/parser/#try_parse_str><code>toml::try_parse_str</code></a> also takes the string to be parsed directly, similar to <code>parse_str</code>. Like <code>try_parse</code>, it uses <a href=https://toruniina.github.io/toml11/docs/reference/result/#result><code>toml::result</code></a> to report errors.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><toml.hpp></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><iostream></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>int</span> <span style=color:#a6e22e>main</span>()
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> parse_result <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>try_parse_str(<span style=color:#e6db74>"title = </span><span style=color:#ae81ff>\"</span><span style=color:#e6db74>parse_str</span><span style=color:#ae81ff>\"</span><span style=color:#e6db74>"</span>);
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>if</span>(parse_result.is_ok())
|
||||
</span></span><span style=display:flex><span> {
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> parse_result.unwrap().at(<span style=color:#e6db74>"title"</span>).as_string() <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span><span style=display:flex><span> }
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>else</span>
|
||||
</span></span><span style=display:flex><span> {
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cerr <span style=color:#f92672><<</span> parse_result.unwrap_err().at(<span style=color:#ae81ff>0</span>) <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span><span style=display:flex><span> }
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> <span style=color:#ae81ff>0</span>;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><h2 id=parsing-byte-arrays>Parsing Byte Arrays
|
||||
<a class=anchor href=#parsing-byte-arrays>#</a></h2><p>It is also possible to parse byte arrays instead of files.</p><p>Since the byte arrays must be encoded in UTF-8, <code>unsigned char</code> is used.</p><h3 id=tomlparsestdvectorunsigned-char><code>toml::parse(std::vector<unsigned char>)</code>
|
||||
<a class=anchor href=#tomlparsestdvectorunsigned-char>#</a></h3><p>The behavior is the same as <a href=https://toruniina.github.io/toml11/docs/reference/parser/#parse><code>toml::parse</code></a>.</p><p>When parsing byte arrays, a <code>filename</code> is required.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><toml.hpp></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><iostream></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>int</span> <span style=color:#a6e22e>main</span>()
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>vector<span style=color:#f92672><</span><span style=color:#66d9ef>unsigned</span> <span style=color:#66d9ef>char</span><span style=color:#f92672>></span> bytes{<span style=color:#75715e>/* ... */</span>};
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value input <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse(bytes, <span style=color:#e6db74>"internal bytes"</span>);
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> input.at(<span style=color:#e6db74>"title"</span>).as_string() <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> <span style=color:#ae81ff>0</span>;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><h3 id=tomltry_parsestdvectorunsigned-char><code>toml::try_parse(std::vector<unsigned char>)</code>
|
||||
<a class=anchor href=#tomltry_parsestdvectorunsigned-char>#</a></h3><p>The behavior is the same as <a href=https://toruniina.github.io/toml11/docs/reference/parser/#try_parse><code>toml::try_parse</code></a>.</p><p>When parsing byte arrays, a <code>filename</code> is required.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><toml.hpp></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><iostream></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>int</span> <span style=color:#a6e22e>main</span>()
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>vector<span style=color:#f92672><</span><span style=color:#66d9ef>unsigned</span> <span style=color:#66d9ef>char</span><span style=color:#f92672>></span> bytes{<span style=color:#75715e>/* ... */</span>};
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> parse_result <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>try_parse(bytes, <span style=color:#e6db74>"internal bytes"</span>);
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>if</span>(parse_result.is_ok())
|
||||
</span></span><span style=display:flex><span> {
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> parse_result.unwrap().at(<span style=color:#e6db74>"title"</span>).as_string() <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span><span style=display:flex><span> }
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>else</span>
|
||||
</span></span><span style=display:flex><span> {
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cerr <span style=color:#f92672><<</span> parse_result.unwrap_err().at(<span style=color:#ae81ff>0</span>) <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span><span style=display:flex><span> }
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> <span style=color:#ae81ff>0</span>;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div></article><footer class=book-footer><div class="flex flex-wrap justify-between"></div><script>(function(){function e(e){const t=window.getSelection(),n=document.createRange();n.selectNodeContents(e),t.removeAllRanges(),t.addRange(n)}document.querySelectorAll("pre code").forEach(t=>{t.addEventListener("click",function(){if(window.getSelection().toString())return;e(t.parentElement),navigator.clipboard&&navigator.clipboard.writeText(t.parentElement.textContent)})})})()</script></footer><label for=menu-control class="hidden book-menu-overlay"></label></div><aside class=book-toc><div class=book-toc-content><nav id=TableOfContents><ul><li><a href=#parsing-files-and-strings>Parsing Files and Strings</a><ul><li><a href=#parsing-files>Parsing Files</a><ul><li><a href=#tomlparse><code>toml::parse</code></a></li><li><a href=#tomltry_parse><code>toml::try_parse</code></a></li></ul></li><li><a href=#parsing-strings>Parsing Strings</a><ul><li><a href=#tomlparse_str><code>toml::parse_str</code></a></li><li><a href=#tomltry_parse_str><code>toml::try_parse_str</code></a></li></ul></li><li><a href=#parsing-byte-arrays>Parsing Byte Arrays</a><ul><li><a href=#tomlparsestdvectorunsigned-char><code>toml::parse(std::vector<unsigned char>)</code></a></li><li><a href=#tomltry_parsestdvectorunsigned-char><code>toml::try_parse(std::vector<unsigned char>)</code></a></li></ul></li></ul></li></ul></nav></div></aside></main></body></html>
|
||||
126
docs/features/serialize/index.html
Normal file
126
docs/features/serialize/index.html
Normal file
@@ -0,0 +1,126 @@
|
||||
<!doctype html><html lang=en dir=ltr><head><meta charset=UTF-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content='
|
||||
Outputting TOML Files
|
||||
#
|
||||
|
||||
Using toml::format, you can convert a toml::value to a string.
|
||||
#include <toml.hpp>
|
||||
#include <cassert>
|
||||
|
||||
int main()
|
||||
{
|
||||
const toml::value v(toml::table{
|
||||
{"a", 42},
|
||||
{"b", "foo"},
|
||||
});
|
||||
const std::string s = toml::format(v);
|
||||
|
||||
const toml::value u = toml::parse_str(s);
|
||||
|
||||
assert(u.at("a").as_integer() == 42);
|
||||
assert(u.at("b").as_string() == "foo");
|
||||
|
||||
return 0;
|
||||
}
|
||||
If the toml::value contains a table_type, it is interpreted as the root table of the file.
|
||||
If a toml::value containing anything other than table_type is passed, only that value is formatted.'><meta name=theme-color media="(prefers-color-scheme: light)" content="#ffffff"><meta name=theme-color media="(prefers-color-scheme: dark)" content="#343a40"><meta name=color-scheme content="light dark"><meta property="og:url" content="https://toruniina.github.io/toml11/docs/features/serialize/"><meta property="og:site_name" content="toml11"><meta property="og:title" content="serializing values"><meta property="og:description" content='Outputting TOML Files # Using toml::format, you can convert a toml::value to a string.
|
||||
#include <toml.hpp> #include <cassert> int main() { const toml::value v(toml::table{ {"a", 42}, {"b", "foo"}, }); const std::string s = toml::format(v); const toml::value u = toml::parse_str(s); assert(u.at("a").as_integer() == 42); assert(u.at("b").as_string() == "foo"); return 0; } If the toml::value contains a table_type, it is interpreted as the root table of the file.
|
||||
If a toml::value containing anything other than table_type is passed, only that value is formatted.'><meta property="og:locale" content="en"><meta property="og:type" content="article"><meta property="article:section" content="docs"><title>serializing values | toml11</title>
|
||||
<link rel=manifest href=/toml11/manifest.json><link rel=icon href=/toml11/favicon.png><link rel=canonical href=https://toruniina.github.io/toml11/docs/features/serialize/><link rel=alternate hreflang=ja href=https://toruniina.github.io/toml11/ja/docs/features/serialize/ title="serializing values"><link rel=stylesheet href=/toml11/book.min.ddac3efe7ea4c1007ff53e5a8fd67f12517e5d2e99984d8c67a18668f7ecaa03.css integrity="sha256-3aw+/n6kwQB/9T5aj9Z/ElF+XS6ZmE2MZ6GGaPfsqgM=" crossorigin=anonymous><script defer src=/toml11/fuse.min.js></script><script defer src=/toml11/en.search.min.db4a558804ac41f081539588cec8e4a415587801da466728166bb5341dd62411.js integrity="sha256-20pViASsQfCBU5WIzsjkpBVYeAHaRmcoFmu1NB3WJBE=" crossorigin=anonymous></script></head><body dir=ltr><input type=checkbox class="hidden toggle" id=menu-control>
|
||||
<input type=checkbox class="hidden toggle" id=toc-control><main class="container flex"><aside class=book-menu><div class=book-menu-content><nav><h2 class=book-brand><a class="flex align-center" href=/toml11/><span>toml11</span></a></h2><div class="book-search hidden"><input type=text id=book-search-input placeholder=Search aria-label=Search maxlength=64 data-hotkeys=s/><div class="book-search-spinner hidden"></div><ul id=book-search-results></ul></div><script>document.querySelector(".book-search").classList.remove("hidden")</script><ul class=book-languages><li><input type=checkbox id=languages class=toggle>
|
||||
<label for=languages class="flex justify-between"><a role=button class="flex align-center"><img src=/toml11/svg/translate.svg class=book-icon alt=Languages>
|
||||
English</a></label><ul><li><a href=https://toruniina.github.io/toml11/ja/docs/features/serialize/>日本語</a></li></ul></li></ul><ul><li><a href=/toml11/docs/installation/>installation</a><ul></ul></li><li><input type=checkbox id=section-291123c850af98d8b815ccdbb4c33657 class=toggle checked>
|
||||
<label for=section-291123c850af98d8b815ccdbb4c33657 class="flex justify-between"><a href=/toml11/docs/features/>features</a></label><ul><li><a href=/toml11/docs/features/parsing_files/>parsing files</a></li><li><a href=/toml11/docs/features/value/>getting values</a></li><li><a href=/toml11/docs/features/error_message/>error message</a></li><li><a href=/toml11/docs/features/serialize/ class=active>serializing values</a></li><li><a href=/toml11/docs/features/configure_types/>configuring types</a></li><li><a href=/toml11/docs/features/literal/>toml literal</a></li><li><a href=/toml11/docs/features/toml_spec/>toml spec</a></li><li><a href=/toml11/docs/features/extension/>extension</a></li></ul></li><li><input type=checkbox id=section-e2e812e55021b82e114feaae98f1a02e class=toggle>
|
||||
<label for=section-e2e812e55021b82e114feaae98f1a02e class="flex justify-between"><a href=/toml11/docs/reference/>reference</a></label><ul><li><a href=/toml11/docs/reference/color/>color.hpp</a></li><li><a href=/toml11/docs/reference/comments/>comments.hpp</a></li><li><a href=/toml11/docs/reference/conversion/>conversion.hpp</a></li><li><a href=/toml11/docs/reference/datetime/>datetime.hpp</a></li><li><a href=/toml11/docs/reference/error_info/>error_info.hpp</a></li><li><a href=/toml11/docs/reference/exception/>exception.hpp</a></li><li><a href=/toml11/docs/reference/find/>find.hpp</a></li><li><a href=/toml11/docs/reference/format/>format.hpp</a></li><li><a href=/toml11/docs/reference/from/>from.hpp</a></li><li><a href=/toml11/docs/reference/get/>get.hpp</a></li><li><a href=/toml11/docs/reference/into/>into.hpp</a></li><li><a href=/toml11/docs/reference/literal/>literal.hpp</a></li><li><a href=/toml11/docs/reference/ordered_map/>ordered_map.hpp</a></li><li><a href=/toml11/docs/reference/parser/>parser.hpp</a></li><li><a href=/toml11/docs/reference/result/>result.hpp</a></li><li><a href=/toml11/docs/reference/serializer/>serializer.hpp</a></li><li><a href=/toml11/docs/reference/source_location/>source_location.hpp</a></li><li><a href=/toml11/docs/reference/spec/>spec.hpp</a></li><li><a href=/toml11/docs/reference/toml_fwd/>toml_fwd.hpp</a></li><li><a href=/toml11/docs/reference/toml/>toml.hpp</a></li><li><a href=/toml11/docs/reference/types/>types.hpp</a></li><li><a href=/toml11/docs/reference/value_t/>value_t.hpp</a></li><li><a href=/toml11/docs/reference/value/>value.hpp</a></li><li><a href=/toml11/docs/reference/version/>version.hpp</a></li><li><a href=/toml11/docs/reference/visit/>visit.hpp</a></li></ul></li><li><a href=/toml11/docs/changelog/>changelog</a><ul></ul></li></ul><ul><li><a href=https://github.com/ToruNiina/toml11 target=_blank rel=noopener>GitHub</a></li></ul></nav><script>(function(){var e=document.querySelector("aside .book-menu-content");addEventListener("beforeunload",function(){localStorage.setItem("menu.scrollTop",e.scrollTop)}),e.scrollTop=localStorage.getItem("menu.scrollTop")})()</script></div></aside><div class=book-page><header class=book-header><div class="flex align-center justify-between"><label for=menu-control><img src=/toml11/svg/menu.svg class=book-icon alt=Menu>
|
||||
</label><strong>serializing values</strong>
|
||||
<label for=toc-control><img src=/toml11/svg/toc.svg class=book-icon alt="Table of Contents"></label></div><aside class="hidden clearfix"><nav id=TableOfContents><ul><li><a href=#outputting-toml-files>Outputting TOML Files</a><ul><li><a href=#outputting-with-keys>Outputting with Keys</a></li><li><a href=#specifying-formats>Specifying Formats</a><ul><li><a href=#specifying-integer-formats>Specifying Integer Formats</a></li><li><a href=#single-line-and-multi-line-arrays>Single-Line and Multi-Line Arrays</a></li><li><a href=#inline-tables>Inline Tables</a></li></ul></li><li><a href=#specifying-the-toml-language-version-for-output>Specifying the TOML Language Version for Output</a></li></ul></li></ul></nav></aside></header><article class="markdown book-article"><h1 id=outputting-toml-files>Outputting TOML Files
|
||||
<a class=anchor href=#outputting-toml-files>#</a></h1><p>Using <code>toml::format</code>, you can convert a <code>toml::value</code> to a string.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><toml.hpp></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><cassert></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>int</span> <span style=color:#a6e22e>main</span>()
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value v(toml<span style=color:#f92672>::</span>table{
|
||||
</span></span><span style=display:flex><span> {<span style=color:#e6db74>"a"</span>, <span style=color:#ae81ff>42</span>},
|
||||
</span></span><span style=display:flex><span> {<span style=color:#e6db74>"b"</span>, <span style=color:#e6db74>"foo"</span>},
|
||||
</span></span><span style=display:flex><span> });
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> std<span style=color:#f92672>::</span>string s <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>format(v);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value u <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse_str(s);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> assert(u.at(<span style=color:#e6db74>"a"</span>).as_integer() <span style=color:#f92672>==</span> <span style=color:#ae81ff>42</span>);
|
||||
</span></span><span style=display:flex><span> assert(u.at(<span style=color:#e6db74>"b"</span>).as_string() <span style=color:#f92672>==</span> <span style=color:#e6db74>"foo"</span>);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> <span style=color:#ae81ff>0</span>;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><p>If the <code>toml::value</code> contains a <code>table_type</code>, it is interpreted as the root table of the file.</p><p>If a <code>toml::value</code> containing anything other than <code>table_type</code> is passed, only that value is formatted.</p><p>Certain format specifications may require a key to be provided for formatting. For example, <code>toml::array_format::array_of_tables</code> formats as <code>[[array.of.tables]]</code>, which requires key access.</p><p>If a format specification that requires a key is provided without a key, a <code>toml::serialization_error</code> is thrown.</p><p>Additionally, if there are values that contradict the format specification, a <code>toml::serialization_error</code> is thrown. For instance, specifying <code>integer_format::hex</code> for a negative integer, or <code>string_format::literal</code> for a string containing newlines, will cause an error.</p><p>The method for specifying formats is explained later.</p><h2 id=outputting-with-keys>Outputting with Keys
|
||||
<a class=anchor href=#outputting-with-keys>#</a></h2><p>You can pass a key to <code>toml::format</code> as a <code>std::string</code>.</p><p>In this case, the key is considered to be under the root table, and the passed value corresponds to that key.</p><p>For nested keys, you can pass a <code>std::vector<std::string></code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><toml.hpp></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><cassert></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>int</span> <span style=color:#a6e22e>main</span>()
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value v(toml<span style=color:#f92672>::</span>table{
|
||||
</span></span><span style=display:flex><span> {<span style=color:#e6db74>"a"</span>, <span style=color:#ae81ff>42</span>},
|
||||
</span></span><span style=display:flex><span> {<span style=color:#e6db74>"b"</span>, <span style=color:#e6db74>"foo"</span>},
|
||||
</span></span><span style=display:flex><span> });
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> std<span style=color:#f92672>::</span>string s <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>format(<span style=color:#e6db74>"bar"</span>, v);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value u <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse_str(s);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> assert(u.at(<span style=color:#e6db74>"bar"</span>).at(<span style=color:#e6db74>"a"</span>).as_integer() <span style=color:#f92672>==</span> <span style=color:#ae81ff>42</span>);
|
||||
</span></span><span style=display:flex><span> assert(u.at(<span style=color:#e6db74>"bar"</span>).at(<span style=color:#e6db74>"b"</span>).as_string() <span style=color:#f92672>==</span> <span style=color:#e6db74>"foo"</span>);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> <span style=color:#ae81ff>0</span>;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><h2 id=specifying-formats>Specifying Formats
|
||||
<a class=anchor href=#specifying-formats>#</a></h2><p>Each type in <code>toml::value</code> has a corresponding format information type.</p><p>For <code>toml::value::integer_type</code>, there is <code>toml::integer_format_info</code>.
|
||||
For <code>toml::value::table_type</code>, there is <code>toml::table_format_info</code>.</p><p>These format information types are set when parsing and are retained even if the value is changed, as long as the type remains the same.</p><p>You can access and directly edit these formats using member functions like <code>as_integer_fmt()</code> or <code>as_table_fmt()</code>.</p><p>Below are some examples explaining how to use these formats.</p><p>For more details on how to access formats, refer to the <a href=https://toruniina.github.io/toml11/docs/reference/value/><code>toml::value</code> reference</a>. For a complete list and detailed information on format information classes, see the <a href=https://toruniina.github.io/toml11/docs/reference/format/>format reference</a>.</p><h3 id=specifying-integer-formats>Specifying Integer Formats
|
||||
<a class=anchor href=#specifying-integer-formats>#</a></h3><p>For integers, you can specify the radix, width, and the position of <code>_</code>.</p><p>When using <code>hex</code>, <code>oct</code>, or <code>bin</code>, values are padded with zeros until the specified width is reached. For <code>dec</code>, the width specification adds spaces, which are not parsed.</p><p>For more details, see the <a href=https://toruniina.github.io/toml11/docs/reference/format/#integer_format>integer format reference</a>.</p><h3 id=single-line-and-multi-line-arrays>Single-Line and Multi-Line Arrays
|
||||
<a class=anchor href=#single-line-and-multi-line-arrays>#</a></h3><p>For arrays, you can specify <code>toml::array_format::oneline</code> or <code>toml::array_format::multiline</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#75715e># oneline</span>
|
||||
</span></span><span style=display:flex><span><span style=color:#a6e22e>a</span> = [<span style=color:#ae81ff>1</span>, <span style=color:#ae81ff>2</span>, <span style=color:#ae81ff>3</span>, <span style=color:#ae81ff>4</span>, <span style=color:#ae81ff>5</span>]
|
||||
</span></span><span style=display:flex><span><span style=color:#75715e># multiline</span>
|
||||
</span></span><span style=display:flex><span><span style=color:#a6e22e>a</span> = [
|
||||
</span></span><span style=display:flex><span> <span style=color:#ae81ff>1</span>,
|
||||
</span></span><span style=display:flex><span> <span style=color:#ae81ff>2</span>,
|
||||
</span></span><span style=display:flex><span> <span style=color:#ae81ff>3</span>,
|
||||
</span></span><span style=display:flex><span> <span style=color:#ae81ff>4</span>,
|
||||
</span></span><span style=display:flex><span> <span style=color:#ae81ff>5</span>
|
||||
</span></span><span style=display:flex><span>]
|
||||
</span></span></code></pre></div><p>When using <code>multiline</code>, you can specify the indentation. Each element is indented by the amount specified in <code>body_indent</code>, and the closing bracket <code>]</code> is indented by the amount specified in <code>closing_indent</code>.</p><p>The type of character used for indentation is specified by <code>indent_type</code>, and you can choose between <code>toml::indent_char::space</code> or <code>toml::indent_char::tab</code>.</p><blockquote class="book-hint warning"><p>Ensure that the same type of character is used for indentation throughout the document.</p><p>If different types of characters are specified for indentation within the same file, the result is undefined. Some form of indentation will be applied, but the type of character and the depth of the indentation may be inconsistent.</p></blockquote><p>If all elements of an <code>array</code> have <code>table_type</code>, you can specify <code>toml::array_format::array_of_tables</code>.</p><p>If you do not specify <code>array_of_tables</code> and use <code>multiline</code>, the tables will be formatted as inline tables.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#75715e># multiline</span>
|
||||
</span></span><span style=display:flex><span><span style=color:#a6e22e>a</span> = [
|
||||
</span></span><span style=display:flex><span> {<span style=color:#a6e22e>foo</span> = <span style=color:#ae81ff>42</span>},
|
||||
</span></span><span style=display:flex><span> {<span style=color:#a6e22e>bar</span> = <span style=color:#e6db74>"hoge"</span>},
|
||||
</span></span><span style=display:flex><span>]
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span><span style=color:#75715e># array_of_tables</span>
|
||||
</span></span><span style=display:flex><span>[[<span style=color:#a6e22e>a</span>]]
|
||||
</span></span><span style=display:flex><span><span style=color:#a6e22e>foo</span> = <span style=color:#ae81ff>42</span>
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span>[[<span style=color:#a6e22e>a</span>]]
|
||||
</span></span><span style=display:flex><span><span style=color:#a6e22e>bar</span> = <span style=color:#e6db74>"hoge"</span>
|
||||
</span></span></code></pre></div><p>By default, <code>toml::array_format::default_format</code> is used. This automatically selects an appropriate format.</p><p>For example, with <code>default_format</code>, if all elements are <code>table_type</code>, it will choose <code>array_of_tables</code>. Short arrays are formatted as <code>oneline</code>, while long or nested arrays, or those with complex elements, are formatted as <code>multiline</code>.</p><p>For more details, see the <a href=https://toruniina.github.io/toml11/docs/reference/format/#array_format>array format reference</a>.</p><h3 id=inline-tables>Inline Tables
|
||||
<a class=anchor href=#inline-tables>#</a></h3><p>To format a table as an inline table, specify <code>toml::table_format::oneline</code>.
|
||||
For standard tables, use <code>toml::table_format::multiline</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#a6e22e>oneline</span> = {<span style=color:#a6e22e>a</span> = <span style=color:#ae81ff>42</span>, <span style=color:#a6e22e>b</span> = <span style=color:#e6db74>"foo"</span>}
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span>[<span style=color:#a6e22e>multiline</span>]
|
||||
</span></span><span style=display:flex><span><span style=color:#a6e22e>a</span> = <span style=color:#ae81ff>42</span>
|
||||
</span></span><span style=display:flex><span><span style=color:#a6e22e>b</span> = <span style=color:#e6db74>"foo"</span>
|
||||
</span></span></code></pre></div><p>In TOML v1.1.0, line breaks within inline tables are allowed. In this case, use <code>toml::table_format::multiline_oneline</code>. This is only applied if the corresponding feature flag is set to <code>true</code> as per the TOML version specification described later.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#a6e22e>multiline_oneline</span> = {
|
||||
</span></span><span style=display:flex><span> <span style=color:#a6e22e>a</span> = <span style=color:#ae81ff>42</span>,
|
||||
</span></span><span style=display:flex><span> <span style=color:#a6e22e>b</span> = <span style=color:#e6db74>"foo"</span>
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><p>For more details, see the <a href=https://toruniina.github.io/toml11/docs/reference/format/#table_format>table format reference</a>.</p><h2 id=specifying-the-toml-language-version-for-output>Specifying the TOML Language Version for Output
|
||||
<a class=anchor href=#specifying-the-toml-language-version-for-output>#</a></h2><p>Certain language features, such as line breaks within inline tables and <code>\x</code> escape sequences, are only available after TOML v1.1.0.</p><p>The <code>toml::format</code> function accepts a <code>toml::spec</code> as its argument.</p><p>This allows you to specify the version of TOML to use during serialization.</p><p>When you use <code>toml::parse</code> with a <code>toml::spec</code> to leverage new features,
|
||||
the parsed values may contain format information that is only compatible with that specific version.
|
||||
Ensure that you pass the same <code>toml::spec</code> to <code>toml::format</code> to maintain compatibility.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><toml.hpp></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><iostream></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>int</span> <span style=color:#a6e22e>main</span>()
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> spec <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>spec<span style=color:#f92672>::</span>v(<span style=color:#ae81ff>1</span>, <span style=color:#ae81ff>1</span>, <span style=color:#ae81ff>0</span>);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value v <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse(<span style=color:#e6db74>"input.toml"</span>, spec);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> toml<span style=color:#f92672>::</span>format(v, spec) <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> <span style=color:#ae81ff>0</span>;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div></article><footer class=book-footer><div class="flex flex-wrap justify-between"></div><script>(function(){function e(e){const t=window.getSelection(),n=document.createRange();n.selectNodeContents(e),t.removeAllRanges(),t.addRange(n)}document.querySelectorAll("pre code").forEach(t=>{t.addEventListener("click",function(){if(window.getSelection().toString())return;e(t.parentElement),navigator.clipboard&&navigator.clipboard.writeText(t.parentElement.textContent)})})})()</script></footer><label for=menu-control class="hidden book-menu-overlay"></label></div><aside class=book-toc><div class=book-toc-content><nav id=TableOfContents><ul><li><a href=#outputting-toml-files>Outputting TOML Files</a><ul><li><a href=#outputting-with-keys>Outputting with Keys</a></li><li><a href=#specifying-formats>Specifying Formats</a><ul><li><a href=#specifying-integer-formats>Specifying Integer Formats</a></li><li><a href=#single-line-and-multi-line-arrays>Single-Line and Multi-Line Arrays</a></li><li><a href=#inline-tables>Inline Tables</a></li></ul></li><li><a href=#specifying-the-toml-language-version-for-output>Specifying the TOML Language Version for Output</a></li></ul></li></ul></nav></div></aside></main></body></html>
|
||||
83
docs/features/toml_spec/index.html
Normal file
83
docs/features/toml_spec/index.html
Normal file
@@ -0,0 +1,83 @@
|
||||
<!doctype html><html lang=en dir=ltr><head><meta charset=UTF-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="
|
||||
TOML Language Version
|
||||
#
|
||||
|
||||
You can specify the version of the TOML language and individual feature flags to use with toml::parse or toml::format through toml::spec.
|
||||
|
||||
Specifying TOML Version
|
||||
#
|
||||
|
||||
You can construct a toml::spec from toml::semantic_version.
|
||||
#include <toml.hpp>
|
||||
|
||||
int main()
|
||||
{
|
||||
toml::spec spec(toml::semantic_version(1, 1, 0));
|
||||
return 0;
|
||||
}
|
||||
However, to make this shorter, the toml::spec::v() function is provided.
|
||||
#include <toml.hpp>
|
||||
|
||||
int main()
|
||||
{
|
||||
toml::spec spec = toml::spec::v(1, 1, 0);
|
||||
return 0;
|
||||
}
|
||||
If not specified explicitly, toml::spec::default_version() is used to construct with default values."><meta name=theme-color media="(prefers-color-scheme: light)" content="#ffffff"><meta name=theme-color media="(prefers-color-scheme: dark)" content="#343a40"><meta name=color-scheme content="light dark"><meta property="og:url" content="https://toruniina.github.io/toml11/docs/features/toml_spec/"><meta property="og:site_name" content="toml11"><meta property="og:title" content="toml spec"><meta property="og:description" content="TOML Language Version # You can specify the version of the TOML language and individual feature flags to use with toml::parse or toml::format through toml::spec.
|
||||
Specifying TOML Version # You can construct a toml::spec from toml::semantic_version.
|
||||
#include <toml.hpp> int main() { toml::spec spec(toml::semantic_version(1, 1, 0)); return 0; } However, to make this shorter, the toml::spec::v() function is provided.
|
||||
#include <toml.hpp> int main() { toml::spec spec = toml::spec::v(1, 1, 0); return 0; } If not specified explicitly, toml::spec::default_version() is used to construct with default values."><meta property="og:locale" content="en"><meta property="og:type" content="article"><meta property="article:section" content="docs"><title>toml spec | toml11</title>
|
||||
<link rel=manifest href=/toml11/manifest.json><link rel=icon href=/toml11/favicon.png><link rel=canonical href=https://toruniina.github.io/toml11/docs/features/toml_spec/><link rel=alternate hreflang=ja href=https://toruniina.github.io/toml11/ja/docs/features/toml_spec/ title="toml spec"><link rel=stylesheet href=/toml11/book.min.ddac3efe7ea4c1007ff53e5a8fd67f12517e5d2e99984d8c67a18668f7ecaa03.css integrity="sha256-3aw+/n6kwQB/9T5aj9Z/ElF+XS6ZmE2MZ6GGaPfsqgM=" crossorigin=anonymous><script defer src=/toml11/fuse.min.js></script><script defer src=/toml11/en.search.min.db4a558804ac41f081539588cec8e4a415587801da466728166bb5341dd62411.js integrity="sha256-20pViASsQfCBU5WIzsjkpBVYeAHaRmcoFmu1NB3WJBE=" crossorigin=anonymous></script></head><body dir=ltr><input type=checkbox class="hidden toggle" id=menu-control>
|
||||
<input type=checkbox class="hidden toggle" id=toc-control><main class="container flex"><aside class=book-menu><div class=book-menu-content><nav><h2 class=book-brand><a class="flex align-center" href=/toml11/><span>toml11</span></a></h2><div class="book-search hidden"><input type=text id=book-search-input placeholder=Search aria-label=Search maxlength=64 data-hotkeys=s/><div class="book-search-spinner hidden"></div><ul id=book-search-results></ul></div><script>document.querySelector(".book-search").classList.remove("hidden")</script><ul class=book-languages><li><input type=checkbox id=languages class=toggle>
|
||||
<label for=languages class="flex justify-between"><a role=button class="flex align-center"><img src=/toml11/svg/translate.svg class=book-icon alt=Languages>
|
||||
English</a></label><ul><li><a href=https://toruniina.github.io/toml11/ja/docs/features/toml_spec/>日本語</a></li></ul></li></ul><ul><li><a href=/toml11/docs/installation/>installation</a><ul></ul></li><li><input type=checkbox id=section-291123c850af98d8b815ccdbb4c33657 class=toggle checked>
|
||||
<label for=section-291123c850af98d8b815ccdbb4c33657 class="flex justify-between"><a href=/toml11/docs/features/>features</a></label><ul><li><a href=/toml11/docs/features/parsing_files/>parsing files</a></li><li><a href=/toml11/docs/features/value/>getting values</a></li><li><a href=/toml11/docs/features/error_message/>error message</a></li><li><a href=/toml11/docs/features/serialize/>serializing values</a></li><li><a href=/toml11/docs/features/configure_types/>configuring types</a></li><li><a href=/toml11/docs/features/literal/>toml literal</a></li><li><a href=/toml11/docs/features/toml_spec/ class=active>toml spec</a></li><li><a href=/toml11/docs/features/extension/>extension</a></li></ul></li><li><input type=checkbox id=section-e2e812e55021b82e114feaae98f1a02e class=toggle>
|
||||
<label for=section-e2e812e55021b82e114feaae98f1a02e class="flex justify-between"><a href=/toml11/docs/reference/>reference</a></label><ul><li><a href=/toml11/docs/reference/color/>color.hpp</a></li><li><a href=/toml11/docs/reference/comments/>comments.hpp</a></li><li><a href=/toml11/docs/reference/conversion/>conversion.hpp</a></li><li><a href=/toml11/docs/reference/datetime/>datetime.hpp</a></li><li><a href=/toml11/docs/reference/error_info/>error_info.hpp</a></li><li><a href=/toml11/docs/reference/exception/>exception.hpp</a></li><li><a href=/toml11/docs/reference/find/>find.hpp</a></li><li><a href=/toml11/docs/reference/format/>format.hpp</a></li><li><a href=/toml11/docs/reference/from/>from.hpp</a></li><li><a href=/toml11/docs/reference/get/>get.hpp</a></li><li><a href=/toml11/docs/reference/into/>into.hpp</a></li><li><a href=/toml11/docs/reference/literal/>literal.hpp</a></li><li><a href=/toml11/docs/reference/ordered_map/>ordered_map.hpp</a></li><li><a href=/toml11/docs/reference/parser/>parser.hpp</a></li><li><a href=/toml11/docs/reference/result/>result.hpp</a></li><li><a href=/toml11/docs/reference/serializer/>serializer.hpp</a></li><li><a href=/toml11/docs/reference/source_location/>source_location.hpp</a></li><li><a href=/toml11/docs/reference/spec/>spec.hpp</a></li><li><a href=/toml11/docs/reference/toml_fwd/>toml_fwd.hpp</a></li><li><a href=/toml11/docs/reference/toml/>toml.hpp</a></li><li><a href=/toml11/docs/reference/types/>types.hpp</a></li><li><a href=/toml11/docs/reference/value_t/>value_t.hpp</a></li><li><a href=/toml11/docs/reference/value/>value.hpp</a></li><li><a href=/toml11/docs/reference/version/>version.hpp</a></li><li><a href=/toml11/docs/reference/visit/>visit.hpp</a></li></ul></li><li><a href=/toml11/docs/changelog/>changelog</a><ul></ul></li></ul><ul><li><a href=https://github.com/ToruNiina/toml11 target=_blank rel=noopener>GitHub</a></li></ul></nav><script>(function(){var e=document.querySelector("aside .book-menu-content");addEventListener("beforeunload",function(){localStorage.setItem("menu.scrollTop",e.scrollTop)}),e.scrollTop=localStorage.getItem("menu.scrollTop")})()</script></div></aside><div class=book-page><header class=book-header><div class="flex align-center justify-between"><label for=menu-control><img src=/toml11/svg/menu.svg class=book-icon alt=Menu>
|
||||
</label><strong>toml spec</strong>
|
||||
<label for=toc-control><img src=/toml11/svg/toc.svg class=book-icon alt="Table of Contents"></label></div><aside class="hidden clearfix"><nav id=TableOfContents><ul><li><a href=#toml-language-version>TOML Language Version</a><ul><li><a href=#specifying-toml-version>Specifying TOML Version</a><ul><li><a href=#parsing-with-version-specification>Parsing with Version Specification</a></li><li><a href=#serializing-with-version-specification>Serializing with Version Specification</a></li></ul></li><li><a href=#specifying-newly-added-features-in-toml>Specifying Newly Added Features in TOML</a></li></ul></li></ul></nav></aside></header><article class="markdown book-article"><h1 id=toml-language-version>TOML Language Version
|
||||
<a class=anchor href=#toml-language-version>#</a></h1><p>You can specify the version of the TOML language and individual feature flags to use with <code>toml::parse</code> or <code>toml::format</code> through <a href=https://toruniina.github.io/toml11/docs/reference/spec/#tomlspec><code>toml::spec</code></a>.</p><h2 id=specifying-toml-version>Specifying TOML Version
|
||||
<a class=anchor href=#specifying-toml-version>#</a></h2><p>You can construct a <a href=https://toruniina.github.io/toml11/docs/reference/spec/#tomlspec><code>toml::spec</code></a> from <a href=https://toruniina.github.io/toml11/docs/reference/spec/#tomlsemantic_version><code>toml::semantic_version</code></a>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><toml.hpp></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>int</span> <span style=color:#a6e22e>main</span>()
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> toml<span style=color:#f92672>::</span>spec spec(toml<span style=color:#f92672>::</span>semantic_version(<span style=color:#ae81ff>1</span>, <span style=color:#ae81ff>1</span>, <span style=color:#ae81ff>0</span>));
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> <span style=color:#ae81ff>0</span>;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><p>However, to make this shorter, the <code>toml::spec::v()</code> function is provided.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><toml.hpp></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>int</span> <span style=color:#a6e22e>main</span>()
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> toml<span style=color:#f92672>::</span>spec spec <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>spec<span style=color:#f92672>::</span>v(<span style=color:#ae81ff>1</span>, <span style=color:#ae81ff>1</span>, <span style=color:#ae81ff>0</span>);
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> <span style=color:#ae81ff>0</span>;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><p>If not specified explicitly, <code>toml::spec::default_version()</code> is used to construct with default values.</p><p>The default value depends on the version of toml11 and follows the latest version of the TOML language released at that time.</p><p>As of v4.4.0, TOML v1.1.0 has not been released yet, so the default TOML version is v1.0.0.</p><blockquote class="book-hint warning"><p>Some features of TOML v1.1.0 are still under fairly lengthy discussion and may still be reverted.</p><p>If they are indeed reverted, toml11 will remove those features in a minor version upgrade or move them to a corresponding later version.</p><p>As such, any features related to future versions should be considered unstable.</p></blockquote><h3 id=parsing-with-version-specification>Parsing with Version Specification
|
||||
<a class=anchor href=#parsing-with-version-specification>#</a></h3><p>The overload of <a href=https://toruniina.github.io/toml11/docs/reference/parser/#parse><code>toml::parse</code></a> takes a <code>toml::spec</code> following the file name.</p><p>This allows you to change the TOML version being used.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><toml.hpp></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>int</span> <span style=color:#a6e22e>main</span>()
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> toml<span style=color:#f92672>::</span>value input <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse(<span style=color:#e6db74>"input.toml"</span>, toml<span style=color:#f92672>::</span>spec<span style=color:#f92672>::</span>v(<span style=color:#ae81ff>1</span>, <span style=color:#ae81ff>1</span>, <span style=color:#ae81ff>0</span>));
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> <span style=color:#ae81ff>0</span>;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><h3 id=serializing-with-version-specification>Serializing with Version Specification
|
||||
<a class=anchor href=#serializing-with-version-specification>#</a></h3><p>The overload of <a href=https://toruniina.github.io/toml11/docs/reference/serializer/><code>toml::format</code></a> takes a <code>toml::spec</code> following the <code>toml::value</code>.</p><p>This allows you to change the TOML version being used.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><toml.hpp></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>int</span> <span style=color:#a6e22e>main</span>()
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> toml<span style=color:#f92672>::</span>value v <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse(<span style=color:#e6db74>"input.toml"</span>, toml<span style=color:#f92672>::</span>spec<span style=color:#f92672>::</span>v(<span style=color:#ae81ff>1</span>, <span style=color:#ae81ff>1</span>, <span style=color:#ae81ff>0</span>));
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> toml<span style=color:#f92672>::</span>format(v, toml<span style=color:#f92672>::</span>spec<span style=color:#f92672>::</span>v(<span style=color:#ae81ff>1</span>, <span style=color:#ae81ff>1</span>, <span style=color:#ae81ff>0</span>)) <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> <span style=color:#ae81ff>0</span>;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><p>If a format is passed that is not permitted by the provided <code>toml::spec</code>, it will be ignored, and another format will be used as a fallback.</p><h2 id=specifying-newly-added-features-in-toml>Specifying Newly Added Features in TOML
|
||||
<a class=anchor href=#specifying-newly-added-features-in-toml>#</a></h2><p>With version upgrades in TOML, multiple new features are introduced, and it’s possible to enable only some of them.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><toml.hpp></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>int</span> <span style=color:#a6e22e>main</span>()
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> toml<span style=color:#f92672>::</span>spec spec <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>spec<span style=color:#f92672>::</span>v(<span style=color:#ae81ff>1</span>, <span style=color:#ae81ff>0</span>, <span style=color:#ae81ff>0</span>);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#75715e>// Allowing newlines in inline tables
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span> spec.v1_1_0_allow_newlines_in_inline_tables <span style=color:#f92672>=</span> true;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> toml<span style=color:#f92672>::</span>value input <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse(<span style=color:#e6db74>"input.toml"</span>, spec);
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> <span style=color:#ae81ff>0</span>;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><p>For a full list of all flags, refer to <a href=https://toruniina.github.io/toml11/docs/reference/spec/#tomlspec><code>toml::spec</code></a>.</p></article><footer class=book-footer><div class="flex flex-wrap justify-between"></div><script>(function(){function e(e){const t=window.getSelection(),n=document.createRange();n.selectNodeContents(e),t.removeAllRanges(),t.addRange(n)}document.querySelectorAll("pre code").forEach(t=>{t.addEventListener("click",function(){if(window.getSelection().toString())return;e(t.parentElement),navigator.clipboard&&navigator.clipboard.writeText(t.parentElement.textContent)})})})()</script></footer><label for=menu-control class="hidden book-menu-overlay"></label></div><aside class=book-toc><div class=book-toc-content><nav id=TableOfContents><ul><li><a href=#toml-language-version>TOML Language Version</a><ul><li><a href=#specifying-toml-version>Specifying TOML Version</a><ul><li><a href=#parsing-with-version-specification>Parsing with Version Specification</a></li><li><a href=#serializing-with-version-specification>Serializing with Version Specification</a></li></ul></li><li><a href=#specifying-newly-added-features-in-toml>Specifying Newly Added Features in TOML</a></li></ul></li></ul></nav></div></aside></main></body></html>
|
||||
440
docs/features/value/index.html
Normal file
440
docs/features/value/index.html
Normal file
@@ -0,0 +1,440 @@
|
||||
<!doctype html><html lang=en dir=ltr><head><meta charset=UTF-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="
|
||||
Retrieving Values
|
||||
#
|
||||
|
||||
This section explains how to access the values stored in toml::value.
|
||||
|
||||
Accessing Values Using Member Functions
|
||||
#
|
||||
|
||||
|
||||
is_something and as_something
|
||||
#
|
||||
|
||||
toml::value has member functions like is_boolean() and is_integer() which allow you to check the type of the stored value.
|
||||
Additionally, it has member functions like as_boolean() and as_integer() that allow you to access the value of that type.
|
||||
For a complete list, refer to the toml::value reference."><meta name=theme-color media="(prefers-color-scheme: light)" content="#ffffff"><meta name=theme-color media="(prefers-color-scheme: dark)" content="#343a40"><meta name=color-scheme content="light dark"><meta property="og:url" content="https://toruniina.github.io/toml11/docs/features/value/"><meta property="og:site_name" content="toml11"><meta property="og:title" content="getting values"><meta property="og:description" content="Retrieving Values # This section explains how to access the values stored in toml::value.
|
||||
Accessing Values Using Member Functions # is_something and as_something # toml::value has member functions like is_boolean() and is_integer() which allow you to check the type of the stored value.
|
||||
Additionally, it has member functions like as_boolean() and as_integer() that allow you to access the value of that type.
|
||||
For a complete list, refer to the toml::value reference."><meta property="og:locale" content="en"><meta property="og:type" content="article"><meta property="article:section" content="docs"><title>getting values | toml11</title>
|
||||
<link rel=manifest href=/toml11/manifest.json><link rel=icon href=/toml11/favicon.png><link rel=canonical href=https://toruniina.github.io/toml11/docs/features/value/><link rel=alternate hreflang=ja href=https://toruniina.github.io/toml11/ja/docs/features/value/ title="getting values"><link rel=stylesheet href=/toml11/book.min.ddac3efe7ea4c1007ff53e5a8fd67f12517e5d2e99984d8c67a18668f7ecaa03.css integrity="sha256-3aw+/n6kwQB/9T5aj9Z/ElF+XS6ZmE2MZ6GGaPfsqgM=" crossorigin=anonymous><script defer src=/toml11/fuse.min.js></script><script defer src=/toml11/en.search.min.db4a558804ac41f081539588cec8e4a415587801da466728166bb5341dd62411.js integrity="sha256-20pViASsQfCBU5WIzsjkpBVYeAHaRmcoFmu1NB3WJBE=" crossorigin=anonymous></script></head><body dir=ltr><input type=checkbox class="hidden toggle" id=menu-control>
|
||||
<input type=checkbox class="hidden toggle" id=toc-control><main class="container flex"><aside class=book-menu><div class=book-menu-content><nav><h2 class=book-brand><a class="flex align-center" href=/toml11/><span>toml11</span></a></h2><div class="book-search hidden"><input type=text id=book-search-input placeholder=Search aria-label=Search maxlength=64 data-hotkeys=s/><div class="book-search-spinner hidden"></div><ul id=book-search-results></ul></div><script>document.querySelector(".book-search").classList.remove("hidden")</script><ul class=book-languages><li><input type=checkbox id=languages class=toggle>
|
||||
<label for=languages class="flex justify-between"><a role=button class="flex align-center"><img src=/toml11/svg/translate.svg class=book-icon alt=Languages>
|
||||
English</a></label><ul><li><a href=https://toruniina.github.io/toml11/ja/docs/features/value/>日本語</a></li></ul></li></ul><ul><li><a href=/toml11/docs/installation/>installation</a><ul></ul></li><li><input type=checkbox id=section-291123c850af98d8b815ccdbb4c33657 class=toggle checked>
|
||||
<label for=section-291123c850af98d8b815ccdbb4c33657 class="flex justify-between"><a href=/toml11/docs/features/>features</a></label><ul><li><a href=/toml11/docs/features/parsing_files/>parsing files</a></li><li><a href=/toml11/docs/features/value/ class=active>getting values</a></li><li><a href=/toml11/docs/features/error_message/>error message</a></li><li><a href=/toml11/docs/features/serialize/>serializing values</a></li><li><a href=/toml11/docs/features/configure_types/>configuring types</a></li><li><a href=/toml11/docs/features/literal/>toml literal</a></li><li><a href=/toml11/docs/features/toml_spec/>toml spec</a></li><li><a href=/toml11/docs/features/extension/>extension</a></li></ul></li><li><input type=checkbox id=section-e2e812e55021b82e114feaae98f1a02e class=toggle>
|
||||
<label for=section-e2e812e55021b82e114feaae98f1a02e class="flex justify-between"><a href=/toml11/docs/reference/>reference</a></label><ul><li><a href=/toml11/docs/reference/color/>color.hpp</a></li><li><a href=/toml11/docs/reference/comments/>comments.hpp</a></li><li><a href=/toml11/docs/reference/conversion/>conversion.hpp</a></li><li><a href=/toml11/docs/reference/datetime/>datetime.hpp</a></li><li><a href=/toml11/docs/reference/error_info/>error_info.hpp</a></li><li><a href=/toml11/docs/reference/exception/>exception.hpp</a></li><li><a href=/toml11/docs/reference/find/>find.hpp</a></li><li><a href=/toml11/docs/reference/format/>format.hpp</a></li><li><a href=/toml11/docs/reference/from/>from.hpp</a></li><li><a href=/toml11/docs/reference/get/>get.hpp</a></li><li><a href=/toml11/docs/reference/into/>into.hpp</a></li><li><a href=/toml11/docs/reference/literal/>literal.hpp</a></li><li><a href=/toml11/docs/reference/ordered_map/>ordered_map.hpp</a></li><li><a href=/toml11/docs/reference/parser/>parser.hpp</a></li><li><a href=/toml11/docs/reference/result/>result.hpp</a></li><li><a href=/toml11/docs/reference/serializer/>serializer.hpp</a></li><li><a href=/toml11/docs/reference/source_location/>source_location.hpp</a></li><li><a href=/toml11/docs/reference/spec/>spec.hpp</a></li><li><a href=/toml11/docs/reference/toml_fwd/>toml_fwd.hpp</a></li><li><a href=/toml11/docs/reference/toml/>toml.hpp</a></li><li><a href=/toml11/docs/reference/types/>types.hpp</a></li><li><a href=/toml11/docs/reference/value_t/>value_t.hpp</a></li><li><a href=/toml11/docs/reference/value/>value.hpp</a></li><li><a href=/toml11/docs/reference/version/>version.hpp</a></li><li><a href=/toml11/docs/reference/visit/>visit.hpp</a></li></ul></li><li><a href=/toml11/docs/changelog/>changelog</a><ul></ul></li></ul><ul><li><a href=https://github.com/ToruNiina/toml11 target=_blank rel=noopener>GitHub</a></li></ul></nav><script>(function(){var e=document.querySelector("aside .book-menu-content");addEventListener("beforeunload",function(){localStorage.setItem("menu.scrollTop",e.scrollTop)}),e.scrollTop=localStorage.getItem("menu.scrollTop")})()</script></div></aside><div class=book-page><header class=book-header><div class="flex align-center justify-between"><label for=menu-control><img src=/toml11/svg/menu.svg class=book-icon alt=Menu>
|
||||
</label><strong>getting values</strong>
|
||||
<label for=toc-control><img src=/toml11/svg/toc.svg class=book-icon alt="Table of Contents"></label></div><aside class="hidden clearfix"><nav id=TableOfContents><ul><li><a href=#retrieving-values>Retrieving Values</a><ul><li><a href=#accessing-values-using-member-functions>Accessing Values Using Member Functions</a><ul><li><a href=#is_something-and-as_something><code>is_something</code> and <code>as_something</code></a></li><li><a href=#tomlvalue_t><code>toml::value_t</code></a></li><li><a href=#at--contains-size-push_back-emplace_back><code>at</code>, <code>[]</code>, <code>contains</code>, <code>size</code>, <code>push_back</code>, <code>emplace_back</code></a></li></ul></li><li><a href=#accessing-comments>Accessing Comments</a></li><li><a href=#handling-inline-tables-and-dotted-keys>Handling Inline Tables and Dotted Keys</a></li><li><a href=#handling-date-and-time-information>Handling Date and Time Information</a></li><li><a href=#converting-using-tomlgett>Converting Using <code>toml::get<T></code></a><ul><li><a href=#simple-conversions>Simple Conversions</a></li><li><a href=#conditions-for-obtaining-references>Conditions for Obtaining References</a></li><li><a href=#converting-arrays-to-stl-containers>Converting Arrays to STL Containers</a></li><li><a href=#converting-arrays-to-stdpair-or-stdtuple>Converting Arrays to <code>std::pair</code> or <code>std::tuple</code></a></li><li><a href=#converting-nested-arrays>Converting Nested Arrays</a></li><li><a href=#converting-tables-to-stdmap>Converting Tables to <code>std::map</code></a></li></ul></li><li><a href=#using-tomlget_or-to-specify-a-value-on-failure>Using <code>toml::get_or</code> to Specify a Value on Failure</a></li><li><a href=#using-tomlfindt-to-search-and-convert-simultaneously>Using <code>toml::find<T></code> to Search and Convert Simultaneously</a></li><li><a href=#using-tomlfind_or-to-search-and-specify-a-value-on-failure>Using <code>toml::find_or</code> to Search and Specify a Value on Failure</a></li><li><a href=#using-tomlfind_or_default-to-search-and-use-the-default-value-on-failure>Using <code>toml::find_or_default</code> to Search and Use the Default Value on Failure</a></li><li><a href=#tomlfindstdoptionalt><code>toml::find<std::optional<T>></code></a></li><li><a href=#defining-conversions-for-user-defined-types>Defining Conversions for User-Defined Types</a><ul><li><a href=#defining-tomlfrom>Defining <code>toml::from</code></a></li><li><a href=#defining-a-from_toml-member-function>Defining a <code>from_toml</code> Member Function</a></li><li><a href=#constructor-accepting-tomlvalue>Constructor Accepting <code>toml::value</code></a></li></ul></li><li><a href=#applying-functions-with-tomlvisit>Applying Functions with <code>toml::visit</code></a></li><li><a href=#constructing-tomlvalue>Constructing <code>toml::value</code></a></li><li><a href=#converting-to-tomlvalue>Converting to <code>toml::value</code></a><ul><li><a href=#defining-tomlinto>Defining <code>toml::into</code></a></li><li><a href=#defining-into_toml-member-function>Defining <code>into_toml</code> Member Function</a></li></ul></li></ul></li><li><a href=#checking-whether-a-value-has-been-accessed>Checking Whether a Value Has Been Accessed</a></li></ul></nav></aside></header><article class="markdown book-article"><h1 id=retrieving-values>Retrieving Values
|
||||
<a class=anchor href=#retrieving-values>#</a></h1><p>This section explains how to access the values stored in <code>toml::value</code>.</p><h2 id=accessing-values-using-member-functions>Accessing Values Using Member Functions
|
||||
<a class=anchor href=#accessing-values-using-member-functions>#</a></h2><h3 id=is_something-and-as_something><code>is_something</code> and <code>as_something</code>
|
||||
<a class=anchor href=#is_something-and-as_something>#</a></h3><p><code>toml::value</code> has member functions like <code>is_boolean()</code> and <code>is_integer()</code> which allow you to check the type of the stored value.</p><p>Additionally, it has member functions like <code>as_boolean()</code> and <code>as_integer()</code> that allow you to access the value of that type.</p><p>For a complete list, refer to the <a href=https://toruniina.github.io/toml11/docs/reference/value/#is_xxx><code>toml::value</code> reference</a>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v <span style=color:#f92672>=</span> <span style=color:#75715e>/* ... */</span>;
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>if</span>(v.is_string())
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> v.as_string() <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><p>If the stored value is of a different type than specified, a <a href=https://toruniina.github.io/toml11/docs/reference/value/#tomltype_error><code>toml::type_error</code></a> is thrown.</p><p>The <code>what()</code> method will contain a message like the following:</p><pre tabindex=0><code>[error] toml::value::as_string(): bad_cast to string
|
||||
--> input.toml
|
||||
|
|
||||
1 | a = 123_456
|
||||
| ^^^^^^^-- the actual type is integer
|
||||
</code></pre><h3 id=tomlvalue_t><code>toml::value_t</code>
|
||||
<a class=anchor href=#tomlvalue_t>#</a></h3><p>Type information can be identified using <a href=https://toruniina.github.io/toml11/docs/reference/value_t/><code>enum class toml::value_t</code></a>.</p><p>The <a href=https://toruniina.github.io/toml11/docs/reference/value/#type><code>type()</code></a> member function returns the type information of the currently stored value.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v <span style=color:#f92672>=</span> <span style=color:#75715e>/* ... */</span>;
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>switch</span>(v.type())
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml:value_t<span style=color:#f92672>::</span>empty : { <span style=color:#75715e>/*...*/</span> <span style=color:#66d9ef>break</span>; }
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml:value_t<span style=color:#f92672>::</span>boolean : { <span style=color:#75715e>/*...*/</span> <span style=color:#66d9ef>break</span>; }
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml:value_t<span style=color:#f92672>::</span>integer : { <span style=color:#75715e>/*...*/</span> <span style=color:#66d9ef>break</span>; }
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml:value_t<span style=color:#f92672>::</span>floating : { <span style=color:#75715e>/*...*/</span> <span style=color:#66d9ef>break</span>; }
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml:value_t<span style=color:#f92672>::</span>string : { <span style=color:#75715e>/*...*/</span> <span style=color:#66d9ef>break</span>; }
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml:value_t<span style=color:#f92672>::</span>offset_datetime: { <span style=color:#75715e>/*...*/</span> <span style=color:#66d9ef>break</span>; }
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml:value_t<span style=color:#f92672>::</span>local_datetime : { <span style=color:#75715e>/*...*/</span> <span style=color:#66d9ef>break</span>; }
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml:value_t<span style=color:#f92672>::</span>local_date : { <span style=color:#75715e>/*...*/</span> <span style=color:#66d9ef>break</span>; }
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml:value_t<span style=color:#f92672>::</span>local_time : { <span style=color:#75715e>/*...*/</span> <span style=color:#66d9ef>break</span>; }
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml:value_t<span style=color:#f92672>::</span>array : { <span style=color:#75715e>/*...*/</span> <span style=color:#66d9ef>break</span>; }
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml:value_t<span style=color:#f92672>::</span>table : { <span style=color:#75715e>/*...*/</span> <span style=color:#66d9ef>break</span>; }
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>default</span><span style=color:#f92672>:</span> {<span style=color:#66d9ef>break</span>;}
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><p>The <a href=https://toruniina.github.io/toml11/docs/reference/value/#istomlvalue_t><code>is(toml::value_t)</code></a> member function returns <code>true</code> if the stored value is of the given <code>value_t</code> type, otherwise it returns <code>false</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v <span style=color:#f92672>=</span> <span style=color:#75715e>/* ... */</span>;
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>if</span>(v.is(toml<span style=color:#f92672>::</span>value_t<span style=color:#f92672>::</span>integer))
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> v.as_integer() <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><h3 id=at--contains-size-push_back-emplace_back><code>at</code>, <code>[]</code>, <code>contains</code>, <code>size</code>, <code>push_back</code>, <code>emplace_back</code>
|
||||
<a class=anchor href=#at--contains-size-push_back-emplace_back>#</a></h3><p><code>toml::value</code> provides some member functions similar to those of standard library containers.</p><p>These functions internally convert <code>toml::value</code> to the corresponding type and call the respective member functions.</p><h4 id=atstdsize_t-i-operatorstdsize_t-i><code>at(std::size_t i)</code>, <code>operator[](std::size_t i)</code>
|
||||
<a class=anchor href=#atstdsize_t-i-operatorstdsize_t-i>#</a></h4><p>These are equivalent to <code>as_array().at(i)</code> and <code>as_array()[i]</code>.</p><p><code>toml::value</code> uses <code>std::vector<toml::value></code> as <code>array_type</code> by default, so <code>at</code> throws <code>std::out_of_range</code> on error, while <code>operator[]</code> results in undefined behavior.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v(toml<span style=color:#f92672>::</span>array{<span style=color:#ae81ff>1</span>,<span style=color:#ae81ff>2</span>,<span style=color:#ae81ff>3</span>});
|
||||
</span></span><span style=display:flex><span>std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> v.at(<span style=color:#ae81ff>1</span>);
|
||||
</span></span></code></pre></div><p>If the stored type is not <code>array_type</code>, a <code>type_error</code> is thrown.</p><h4 id=atstdstring-key-operatorstdstring-key><code>at(std::string key)</code>, <code>operator[](std::string key)</code>
|
||||
<a class=anchor href=#atstdstring-key-operatorstdstring-key>#</a></h4><p>These are equivalent to <code>as_table().at(key)</code> and <code>as_table()[key]</code>.</p><p><code>toml::value</code> uses <code>std::unordered_map<std::string, toml::value></code> as <code>table_type</code> by default, so if the corresponding value does not exist, <code>at</code> throws <code>std::out_of_range</code>, while <code>operator[]</code> constructs a new <code>toml::value</code> and returns a reference to it. Therefore, there is no <code>const</code> version of <code>operator[]</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v(toml<span style=color:#f92672>::</span>table{});
|
||||
</span></span><span style=display:flex><span>v[<span style=color:#e6db74>"a"</span>] <span style=color:#f92672>=</span> <span style=color:#ae81ff>42</span>;
|
||||
</span></span></code></pre></div><p>If the stored type is not <code>table_type</code>, a <code>type_error</code> is thrown.</p><h4 id=size><code>size()</code>
|
||||
<a class=anchor href=#size>#</a></h4><p>Returns the length.</p><p>For <code>array_type</code> or <code>table_type</code>, it returns the number of elements; for <code>string_type</code>, it returns the number of characters (in bytes).</p><p>If the stored type is none of these, a <code>type_error</code> is thrown.</p><h4 id=push_back-emplace_back><code>push_back()</code>, <code>emplace_back()</code>
|
||||
<a class=anchor href=#push_back-emplace_back>#</a></h4><p>These are equivalent to <code>as_array().push_back()</code> and <code>as_array().emplace_back()</code>.</p><p>If the stored type is not <code>array_type</code>, a <code>type_error</code> is thrown.</p><h2 id=accessing-comments>Accessing Comments
|
||||
<a class=anchor href=#accessing-comments>#</a></h2><p>In toml11, comments are parsed by default and saved line by line with the corresponding value.</p><p>A comment corresponds to the value that comes immediately after the consecutive lines of comments, or to the value on the same line as the comment.</p><p>If there is no value immediately before or after the comment, it is not associated with any value and is ignored.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#75715e># input.toml</span>
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span><span style=color:#75715e># This is a comment about a.</span>
|
||||
</span></span><span style=display:flex><span><span style=color:#a6e22e>a</span> = <span style=color:#ae81ff>42</span>
|
||||
</span></span><span style=display:flex><span><span style=color:#a6e22e>b</span> = <span style=color:#ae81ff>3.14</span> <span style=color:#75715e># This is a comment about b.</span>
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span><span style=color:#75715e># This comment is ignored because it has no corresponding value.</span>
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span><span style=color:#75715e># This is the 1st comment about c.</span>
|
||||
</span></span><span style=display:flex><span><span style=color:#75715e># This is the 2nd comment about c.</span>
|
||||
</span></span><span style=display:flex><span><span style=color:#a6e22e>c</span> = <span style=color:#e6db74>"foo"</span> <span style=color:#75715e># This is the final comment about c.</span>
|
||||
</span></span><span style=display:flex><span><span style=color:#75715e># This comment is NOT a comment about c.</span>
|
||||
</span></span></code></pre></div><p>Comments corresponding to a value can be accessed using the <code>comments()</code> member function of <code>toml::value</code>.</p><p><code>comments()</code> returns a container that has the same member functions as <code>std::vector<std::string></code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> v <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse(<span style=color:#e6db74>"input.toml"</span>);
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span><span style=color:#f92672>&</span> a <span style=color:#f92672>=</span> v.at(<span style=color:#e6db74>"a"</span>);
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span><span style=color:#f92672>&</span> b <span style=color:#f92672>=</span> v.at(<span style=color:#e6db74>"b"</span>);
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span><span style=color:#f92672>&</span> c <span style=color:#f92672>=</span> v.at(<span style=color:#e6db74>"c"</span>);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span>assert(a.comments().size() <span style=color:#f92672>==</span> <span style=color:#ae81ff>1</span>);
|
||||
</span></span><span style=display:flex><span>assert(a.comments().at(<span style=color:#ae81ff>0</span>) <span style=color:#f92672>==</span> <span style=color:#e6db74>"# This is a comment about a."</span>);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span>assert(b.comments().size() <span style=color:#f92672>==</span> <span style=color:#ae81ff>1</span>);
|
||||
</span></span><span style=display:flex><span>assert(b.comments().at(<span style=color:#ae81ff>0</span>) <span style=color:#f92672>==</span> <span style=color:#e6db74>"# This is a comment about b."</span>);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span>assert(c.comments().size() <span style=color:#f92672>==</span> <span style=color:#ae81ff>3</span>);
|
||||
</span></span><span style=display:flex><span>assert(c.comments().at(<span style=color:#ae81ff>0</span>) <span style=color:#f92672>==</span> <span style=color:#e6db74>"# This is the 1st comment about c."</span>);
|
||||
</span></span><span style=display:flex><span>assert(c.comments().at(<span style=color:#ae81ff>1</span>) <span style=color:#f92672>==</span> <span style=color:#e6db74>"# This is the 2nd comment about c."</span>);
|
||||
</span></span><span style=display:flex><span>assert(c.comments().at(<span style=color:#ae81ff>2</span>) <span style=color:#f92672>==</span> <span style=color:#e6db74>"# This is the final comment about c."</span>);
|
||||
</span></span></code></pre></div><p>Comments related to the root table of the entire file are written at the beginning of the file.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#75715e># This is a comment about the root table.</span>
|
||||
</span></span><span style=display:flex><span><span style=color:#75715e># This is also a comment about the root table.</span>
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span><span style=color:#75715e># This comment is ignored.</span>
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span><span style=color:#75715e># This is a comment about a.</span>
|
||||
</span></span><span style=display:flex><span><span style=color:#a6e22e>a</span> = <span style=color:#ae81ff>42</span>
|
||||
</span></span></code></pre></div><p>However, if a value immediately follows the initial comment, the comment is interpreted as pertaining to that value, and there are no comments for the root table.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#75715e># This is a comment about a.</span>
|
||||
</span></span><span style=display:flex><span><span style=color:#75715e># This is also a comment about a.</span>
|
||||
</span></span><span style=display:flex><span><span style=color:#a6e22e>a</span> = <span style=color:#ae81ff>42</span>
|
||||
</span></span></code></pre></div><h2 id=handling-inline-tables-and-dotted-keys>Handling Inline Tables and Dotted Keys
|
||||
<a class=anchor href=#handling-inline-tables-and-dotted-keys>#</a></h2><p>An inline table is simply a table, and there is no difference in handling it compared to other tables in C++ code.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#a6e22e>a</span> = {<span style=color:#a6e22e>b</span> = <span style=color:#ae81ff>42</span>, <span style=color:#a6e22e>c</span> = <span style=color:#e6db74>"foo"</span>}
|
||||
</span></span></code></pre></div><p>Dotted keys are also just tables, with no difference in handling compared to other tables in C++ code.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#a6e22e>a</span>.<span style=color:#a6e22e>b</span> = <span style=color:#ae81ff>42</span>
|
||||
</span></span><span style=display:flex><span><span style=color:#a6e22e>a</span>.<span style=color:#a6e22e>c</span> = <span style=color:#e6db74>"foo"</span>
|
||||
</span></span></code></pre></div><p>These TOML files are identical to the following file.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span>[<span style=color:#a6e22e>a</span>]
|
||||
</span></span><span style=display:flex><span><span style=color:#a6e22e>b</span> = <span style=color:#ae81ff>42</span>
|
||||
</span></span><span style=display:flex><span><span style=color:#a6e22e>c</span> = <span style=color:#e6db74>"foo"</span>
|
||||
</span></span></code></pre></div><p>Thus, they can all be processed with the exact same code.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> input <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse(<span style=color:#e6db74>"input.toml"</span>);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span>assert(input.at(<span style=color:#e6db74>"a"</span>).at(<span style=color:#e6db74>"b"</span>).as_integer() <span style=color:#f92672>==</span> <span style=color:#ae81ff>42</span>);
|
||||
</span></span><span style=display:flex><span>assert(input.at(<span style=color:#e6db74>"a"</span>).at(<span style=color:#e6db74>"c"</span>).as_string() <span style=color:#f92672>==</span> <span style=color:#e6db74>"foo"</span>);
|
||||
</span></span></code></pre></div><p>However, it is possible to distinguish them based on format information.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> input <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse(<span style=color:#e6db74>"input.toml"</span>);
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>switch</span>(input.at(<span style=color:#e6db74>"a"</span>).as_table_fmt().fmt)
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml<span style=color:#f92672>::</span>table_format<span style=color:#f92672>::</span>oneline:
|
||||
</span></span><span style=display:flex><span> {
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> <span style=color:#e6db74>"inline table"</span> <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>break</span>;
|
||||
</span></span><span style=display:flex><span> }
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml<span style=color:#f92672>::</span>table_format<span style=color:#f92672>::</span>multiline:
|
||||
</span></span><span style=display:flex><span> {
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> <span style=color:#e6db74>"normal table"</span> <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>break</span>;
|
||||
</span></span><span style=display:flex><span> }
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml<span style=color:#f92672>::</span>table_format<span style=color:#f92672>::</span>dotted:
|
||||
</span></span><span style=display:flex><span> {
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> <span style=color:#e6db74>"dotted keys"</span> <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>break</span>;
|
||||
</span></span><span style=display:flex><span> }
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span></code></pre></div><p>This format information is also considered during serialization, which will be described later.</p><h2 id=handling-date-and-time-information>Handling Date and Time Information
|
||||
<a class=anchor href=#handling-date-and-time-information>#</a></h2><p><a href=https://toruniina.github.io/toml11/docs/reference/datetime/#local_date><code>local_date</code></a>,
|
||||
<a href=https://toruniina.github.io/toml11/docs/reference/datetime/#local_time><code>local_time</code></a>,
|
||||
<a href=https://toruniina.github.io/toml11/docs/reference/datetime/#local_datetime><code>local_datetime</code></a>, and
|
||||
<a href=https://toruniina.github.io/toml11/docs/reference/datetime/#offset_datetime><code>offset_datetime</code></a>
|
||||
are parsed into dedicated structures with corresponding member variables in toml11.</p><p>When using these, you can directly extract the values or use <code>toml::get</code> and <code>toml::find</code> to convert them into types such as <code>std::chrono::system_clock::time_point</code> or <code>std::tm</code>.</p><h2 id=converting-using-tomlgett>Converting Using <code>toml::get<T></code>
|
||||
<a class=anchor href=#converting-using-tomlgett>#</a></h2><p><code>toml::get<T></code> is a function that converts and retrieves the value stored in <code>toml::value</code>.
|
||||
Specify the desired target type as <code>T</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value v <span style=color:#f92672>=</span> <span style=color:#75715e>/*...*/</span>;
|
||||
</span></span><span style=display:flex><span>std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>></span>(v) <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
||||
</span></span></code></pre></div><p>The <code>toml::find<T></code> function, described later, also has the same functionality for type conversion.</p><p>If an unsupported type is specified for the stored value, a <code>toml::type_error</code> is thrown.</p><h3 id=simple-conversions>Simple Conversions
|
||||
<a class=anchor href=#simple-conversions>#</a></h3><h4 id=boolean_type>boolean_type
|
||||
<a class=anchor href=#boolean_type>#</a></h4><p>Conversion from <code>boolean_type</code> is possible only to <code>bool</code>.</p><h4 id=integer_type>integer_type
|
||||
<a class=anchor href=#integer_type>#</a></h4><p>Any type for which <code>std::is_integral<T></code> is <code>true</code>, except <code>bool</code>, can be converted from <code>integer_type</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v(<span style=color:#ae81ff>42</span>);
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> u32 <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span><span style=color:#66d9ef>uint32_t</span><span style=color:#f92672>></span>(v);
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> i16 <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span><span style=color:#66d9ef>short</span><span style=color:#f92672>></span>(v);
|
||||
</span></span></code></pre></div><h4 id=floating_type>floating_type
|
||||
<a class=anchor href=#floating_type>#</a></h4><p>Any type for which <code>std::is_floating_point<T></code> is <code>true</code> can be converted from <code>floating_type</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v(<span style=color:#ae81ff>3.14</span>);
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> f64 <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span><span style=color:#66d9ef>double</span><span style=color:#f92672>></span>(v);
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> f32 <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span><span style=color:#66d9ef>float</span> <span style=color:#f92672>></span>(v);
|
||||
</span></span></code></pre></div><h4 id=string_type>string_type
|
||||
<a class=anchor href=#string_type>#</a></h4><p><code>string_type</code> can be converted to <code>std::string</code>.
|
||||
From C++17 onwards, it can also be converted to <code>std::string_view</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v(<span style=color:#e6db74>"foo"</span>);
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> s <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>string<span style=color:#f92672>></span>(v);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span><span style=color:#75715e>// C++17
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> sv <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>string_view<span style=color:#f92672>></span>(v);
|
||||
</span></span></code></pre></div><h4 id=datetime-variants>datetime variants
|
||||
<a class=anchor href=#datetime-variants>#</a></h4><p><a href=https://toruniina.github.io/toml11/docs/reference/datetime/#local_date><code>local_date</code></a>,
|
||||
<a href=https://toruniina.github.io/toml11/docs/reference/datetime/#local_datetime><code>local_datetime</code></a>, and
|
||||
<a href=https://toruniina.github.io/toml11/docs/reference/datetime/#offset_datetime><code>offset_datetime</code></a> represent specific dates and times,
|
||||
so they can be converted to <code>std::chrono::system_clock::time_point</code>.</p><p>However, since <a href=https://toruniina.github.io/toml11/docs/reference/datetime/#local_time><code>local_time</code></a> does not include date information, it supports conversion to <code>std::chrono::duration</code> as the elapsed time from <code>00:00.00</code>.</p><p>Additionally, <code>local_date</code> and <code>local_datetime</code> conversions take the executing machine’s timezone into account.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#a6e22e>date</span> = <span style=color:#ae81ff>2024-01-23</span>
|
||||
</span></span><span style=display:flex><span><span style=color:#a6e22e>time</span> = <span style=color:#ae81ff>12</span><span style=color:#960050;background-color:#1e0010>:</span><span style=color:#ae81ff>30</span><span style=color:#960050;background-color:#1e0010>:</span><span style=color:#ae81ff>00</span>
|
||||
</span></span><span style=display:flex><span><span style=color:#a6e22e>l_dt</span> = <span style=color:#ae81ff>2024-01-23</span><span style=color:#a6e22e>T12</span><span style=color:#960050;background-color:#1e0010>:</span><span style=color:#ae81ff>30</span><span style=color:#960050;background-color:#1e0010>:</span><span style=color:#ae81ff>00</span>
|
||||
</span></span><span style=display:flex><span><span style=color:#a6e22e>o_dt</span> = <span style=color:#e6db74>2024-01-23T12:30:00+09:00</span>
|
||||
</span></span></code></pre></div><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> input <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse(<span style=color:#e6db74>"input.toml"</span>);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> date <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>chrono<span style=color:#f92672>::</span>system_clock<span style=color:#f92672>::</span>time_point<span style=color:#f92672>></span>(input.at(<span style=color:#e6db74>"date"</span>));
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> l_dt <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>chrono<span style=color:#f92672>::</span>system_clock<span style=color:#f92672>::</span>time_point<span style=color:#f92672>></span>(input.at(<span style=color:#e6db74>"l_dt"</span>));
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> o_dt <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>chrono<span style=color:#f92672>::</span>system_clock<span style=color:#f92672>::</span>time_point<span style=color:#f92672>></span>(input.at(<span style=color:#e6db74>"o_dt"</span>));
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> time <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>chrono<span style=color:#f92672>::</span>minutes<span style=color:#f92672>></span>(input.at(<span style=color:#e6db74>"time"</span>)); <span style=color:#75715e>// 12 * 60 + 30 min
|
||||
</span></span></span></code></pre></div><h3 id=conditions-for-obtaining-references>Conditions for Obtaining References
|
||||
<a class=anchor href=#conditions-for-obtaining-references>#</a></h3><p><code>toml::get<T></code> can return a reference if <code>T</code> is the exact type stored in <code>toml::value</code>.</p><p>Conversely, if a conversion is necessary (e.g., extracting an integer stored as <code>std::int64_t</code> into <code>std::uint32_t</code>), it is not possible to return a reference to the converted type.</p><p>When no conversion is needed, the returned reference can be used to modify the value.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v(<span style=color:#ae81ff>42</span>);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span>toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>toml<span style=color:#f92672>::</span>value<span style=color:#f92672>::</span>integer_type<span style=color:#f92672>></span>(v) <span style=color:#f92672>=</span> <span style=color:#ae81ff>6</span> <span style=color:#f92672>*</span> <span style=color:#ae81ff>9</span>;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span>assert(v.as_integer() <span style=color:#f92672>==</span> <span style=color:#ae81ff>54</span>);
|
||||
</span></span></code></pre></div><h3 id=converting-arrays-to-stl-containers>Converting Arrays to STL Containers
|
||||
<a class=anchor href=#converting-arrays-to-stl-containers>#</a></h3><p>If all elements in an array have the same type and can be converted to <code>T</code>, it is possible to convert them to <code>std::vector<T></code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#a6e22e>a</span> = [<span style=color:#ae81ff>1</span>, <span style=color:#ae81ff>2</span>, <span style=color:#ae81ff>3</span>, <span style=color:#ae81ff>4</span>, <span style=color:#ae81ff>5</span>]
|
||||
</span></span></code></pre></div><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>vector<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>>></span>(input.at(<span style=color:#e6db74>"a"</span>));
|
||||
</span></span></code></pre></div><p>Other STL containers can also be used.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a1 <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>deque<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>>></span>(input.at(<span style=color:#e6db74>"a"</span>));
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a2 <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>list <span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>>></span>(input.at(<span style=color:#e6db74>"a"</span>));
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a3 <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>array<span style=color:#f92672><</span><span style=color:#66d9ef>int</span>, <span style=color:#ae81ff>5</span><span style=color:#f92672>>></span>(input.at(<span style=color:#e6db74>"a"</span>));
|
||||
</span></span></code></pre></div><p>When converting to <code>std::array</code>, the number of elements must match. If they don’t match, a <code>std::out_of_range</code> exception is thrown.</p><p>Non-STL containers that have a default constructor and a <code>push_back</code> method can also be converted using <code>toml::get</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>boost<span style=color:#f92672>::</span>container<span style=color:#f92672>::</span>small_vector<span style=color:#f92672><</span><span style=color:#66d9ef>int</span>, <span style=color:#ae81ff>8</span><span style=color:#f92672>>></span>(input.at(<span style=color:#e6db74>"a"</span>));
|
||||
</span></span></code></pre></div><h3 id=converting-arrays-to-stdpair-or-stdtuple>Converting Arrays to <code>std::pair</code> or <code>std::tuple</code>
|
||||
<a class=anchor href=#converting-arrays-to-stdpair-or-stdtuple>#</a></h3><p>If an array contains elements of different types, it can be converted to <code>std::pair</code> or <code>std::tuple</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#a6e22e>a</span> = [<span style=color:#66d9ef>true</span>, <span style=color:#ae81ff>3.14</span>]
|
||||
</span></span><span style=display:flex><span><span style=color:#a6e22e>b</span> = [<span style=color:#ae81ff>42</span>, <span style=color:#ae81ff>2.718</span>, <span style=color:#e6db74>"foo"</span>]
|
||||
</span></span></code></pre></div><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>pair<span style=color:#f92672><</span><span style=color:#66d9ef>bool</span>, <span style=color:#66d9ef>double</span><span style=color:#f92672>>></span>(input.at(<span style=color:#e6db74>"a"</span>));
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> b <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>tuple<span style=color:#f92672><</span><span style=color:#66d9ef>int</span>, <span style=color:#66d9ef>double</span>, std<span style=color:#f92672>::</span>string<span style=color:#f92672>>></span>(input.at(<span style=color:#e6db74>"b"</span>));
|
||||
</span></span></code></pre></div><p>As with <code>std::array</code>, the length of the array must match the number of elements in the <code>std::pair</code> or <code>std::tuple</code>. If they don’t match, a <code>std::out_of_range</code> exception is thrown.</p><p>Additionally, each element must be convertible to the corresponding element in the <code>std::pair</code> or <code>std::tuple</code>. If conversion is not possible, a <code>toml::type_error</code> exception is thrown.</p><h3 id=converting-nested-arrays>Converting Nested Arrays
|
||||
<a class=anchor href=#converting-nested-arrays>#</a></h3><p>Nested arrays can be converted to nested containers.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#a6e22e>a</span> = [ [<span style=color:#ae81ff>1</span>, <span style=color:#ae81ff>2</span>, <span style=color:#ae81ff>3</span>], [<span style=color:#ae81ff>4</span>, <span style=color:#ae81ff>5</span>, <span style=color:#ae81ff>6</span>] ]
|
||||
</span></span></code></pre></div><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>vector<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>vector<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>>>></span>(input.at(<span style=color:#e6db74>"a"</span>));
|
||||
</span></span></code></pre></div><p>If the types are different, <code>std::pair</code> or <code>std::tuple</code> can be useful.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#a6e22e>a</span> = [ [<span style=color:#ae81ff>1</span>, <span style=color:#ae81ff>2</span>, <span style=color:#ae81ff>3</span>], [<span style=color:#e6db74>"foo"</span>, <span style=color:#e6db74>"bar"</span>] ]
|
||||
</span></span></code></pre></div><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>pair<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>vector<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>></span>, std<span style=color:#f92672>::</span>vector<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>string<span style=color:#f92672>>></span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#f92672>></span>(input.at(<span style=color:#e6db74>"a"</span>));
|
||||
</span></span></code></pre></div><h3 id=converting-tables-to-stdmap>Converting Tables to <code>std::map</code>
|
||||
<a class=anchor href=#converting-tables-to-stdmap>#</a></h3><p>If all values in a table have the same type, they can be converted to <code>std::map</code> or <code>std::unordered_map</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#a6e22e>t</span> = {<span style=color:#a6e22e>a</span> = <span style=color:#ae81ff>1</span>, <span style=color:#a6e22e>b</span> = <span style=color:#ae81ff>2</span>}
|
||||
</span></span></code></pre></div><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> t <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>map<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>string, <span style=color:#66d9ef>int</span><span style=color:#f92672>>></span>(input.at(<span style=color:#e6db74>"t"</span>));
|
||||
</span></span></code></pre></div><p>Non-STL containers that have a default constructor and an <code>emplace(key, mapped)</code> method can also be converted using <code>toml::get</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> t <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>boost<span style=color:#f92672>::</span>container<span style=color:#f92672>::</span>flat_map<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>string, <span style=color:#66d9ef>int</span><span style=color:#f92672>>></span>(input.at(<span style=color:#e6db74>"t"</span>));
|
||||
</span></span></code></pre></div><p>If the conversion of any element fails, a <code>toml::type_error</code> exception is thrown.</p><h2 id=using-tomlget_or-to-specify-a-value-on-failure>Using <code>toml::get_or</code> to Specify a Value on Failure
|
||||
<a class=anchor href=#using-tomlget_or-to-specify-a-value-on-failure>#</a></h2><p><code>toml::get</code> throws a <code>toml::type_error</code> exception if the conversion fails.</p><p>By using <code>toml::get_or</code>, you can specify a default value to return instead of an exception in case of a conversion failure.</p><p>Unlike <code>toml::get<T></code>, <code>get_or</code> infers the target type from the arguments, so there is no need to specify <code><T></code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get_or(input.at(<span style=color:#e6db74>"a"</span>), <span style=color:#ae81ff>42</span>);
|
||||
</span></span></code></pre></div><p>The types that can be converted are the same as for <code>toml::get</code>.</p><p>If you specify <code>toml::value::xxx_type</code>, you can also retrieve a reference, but in that case, the argument must also be a reference.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>value<span style=color:#f92672>::</span>integer_type a_default <span style=color:#f92672>=</span> <span style=color:#ae81ff>42</span>;
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>auto</span> a<span style=color:#f92672>&</span> <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get_or(input.at(<span style=color:#e6db74>"a"</span>), a_default);
|
||||
</span></span></code></pre></div><h2 id=using-tomlfindt-to-search-and-convert-simultaneously>Using <code>toml::find<T></code> to Search and Convert Simultaneously
|
||||
<a class=anchor href=#using-tomlfindt-to-search-and-convert-simultaneously>#</a></h2><p><code>toml::find<T></code> is a function that searches for a value in a <code>toml::value</code> holding a table and simultaneously performs the same type conversion as <code>toml::get</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>></span>(input, <span style=color:#e6db74>"a"</span>);
|
||||
</span></span><span style=display:flex><span><span style=color:#75715e>// Equivalent to: const auto a = toml::get<int>(input.at("a"));
|
||||
</span></span></span></code></pre></div><p><code>toml::find<T></code> can also be used with arrays.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> input.at(<span style=color:#e6db74>"a"</span>);
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a2 <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>></span>(a, <span style=color:#ae81ff>2</span>);
|
||||
</span></span><span style=display:flex><span><span style=color:#75715e>// Equivalent to: const auto a2 = toml::get<int>(input.at("a").at(2));
|
||||
</span></span></span></code></pre></div><p>If an error occurs during type conversion, <code>toml::find<T></code> throws the same <code>toml::type_error</code> as <code>toml::get</code>.
|
||||
If the key is not found or the index does not exist, it throws <code>std::out_of_range</code>.</p><p>If no type is specified, <code>toml::find</code> returns a <code>toml::value</code> without type conversion.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>find(input, <span style=color:#e6db74>"a"</span>);
|
||||
</span></span><span style=display:flex><span><span style=color:#75715e>// Equivalent to: const auto a = input.at("a");
|
||||
</span></span></span></code></pre></div><p><code>toml::find<T></code> can access values recursively.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#a6e22e>a</span> = {<span style=color:#a6e22e>b</span> = {<span style=color:#a6e22e>c</span> = <span style=color:#ae81ff>42</span>}}
|
||||
</span></span></code></pre></div><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a_b_c <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>></span>(input, <span style=color:#e6db74>"a"</span>, <span style=color:#e6db74>"b"</span>, <span style=color:#e6db74>"c"</span>);
|
||||
</span></span><span style=display:flex><span><span style=color:#75715e>// Equivalent to: const auto a = toml::get<int>(input.at("a").at("b").at("c"));
|
||||
</span></span></span></code></pre></div><p>You can mix keys and indexes.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#a6e22e>a</span> = [ {<span style=color:#a6e22e>b</span> = <span style=color:#ae81ff>1</span>}, {<span style=color:#a6e22e>b</span> = <span style=color:#ae81ff>2</span>}, {<span style=color:#a6e22e>b</span> = <span style=color:#ae81ff>3</span>} ]
|
||||
</span></span></code></pre></div><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a_2_b <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>></span>(input, <span style=color:#e6db74>"a"</span>, <span style=color:#ae81ff>2</span>, <span style=color:#e6db74>"b"</span>);
|
||||
</span></span><span style=display:flex><span><span style=color:#75715e>// Equivalent to: const auto a = toml::get<int>(input.at("a").at(2).at("c"));
|
||||
</span></span></span></code></pre></div><blockquote class="book-hint info"><p>TOML supports a feature called quoted keys, which allows using normally disallowed characters in keys by enclosing them in <code>""</code> or <code>''</code>. Within quoted keys, <code>.</code> does <strong>not</strong> introduce tables.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#e6db74>"127.0.0.1"</span> = <span style=color:#e6db74>"value"</span>
|
||||
</span></span><span style=display:flex><span><span style=color:#a6e22e>site</span>.<span style=color:#e6db74>"google.com"</span> = <span style=color:#66d9ef>true</span>
|
||||
</span></span></code></pre></div><p>You can read this TOML file as follows:</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> input <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse(<span style=color:#e6db74>"input.toml"</span>);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span>assert(input.at(<span style=color:#e6db74>"127.0.0.1"</span>).as_string() <span style=color:#f92672>==</span> <span style=color:#e6db74>"value"</span>);
|
||||
</span></span><span style=display:flex><span>assert(input.at(<span style=color:#e6db74>"site"</span>).at(<span style=color:#e6db74>"google.com"</span>).as_boolean());
|
||||
</span></span></code></pre></div><p>To handle such cases seamlessly, toml11 does not automatically split keys containing <code>.</code>. Explicitly specifying the table hierarchy helps in structuring the input file correctly.</p><p>Reference: <a href=https://toml.io/en/v1.0.0#key>toml.io/Key</a></p></blockquote><h2 id=using-tomlfind_or-to-search-and-specify-a-value-on-failure>Using <code>toml::find_or</code> to Search and Specify a Value on Failure
|
||||
<a class=anchor href=#using-tomlfind_or-to-search-and-specify-a-value-on-failure>#</a></h2><p><code>toml::find_or</code> works similarly to <code>toml::find<T></code>, but allows specifying a default value to return if the search or conversion fails.</p><p>This is useful when you want to provide a fallback value instead of handling exceptions.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>find_or(input, <span style=color:#e6db74>"a"</span>, <span style=color:#ae81ff>42</span>);
|
||||
</span></span></code></pre></div><h2 id=using-tomlfind_or_default-to-search-and-use-the-default-value-on-failure>Using <code>toml::find_or_default</code> to Search and Use the Default Value on Failure
|
||||
<a class=anchor href=#using-tomlfind_or_default-to-search-and-use-the-default-value-on-failure>#</a></h2><p><code>toml::find_or_default</code> works similarly to <code>toml::find_or<T></code> but returns the default constructor result if the search or conversion fails.</p><p>This is useful when you want to use the default value instead of handling exceptions, especially when the default construction is costly, as this delays it until the actual failure happens.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>find_or(input, <span style=color:#e6db74>"a"</span>, expensive()); <span style=color:#75715e>// ctor is called before the function call
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>find_or_default<span style=color:#f92672><</span>expensive<span style=color:#f92672>></span>(input, <span style=color:#e6db74>"a"</span>); <span style=color:#75715e>// ctor will be called only on failure
|
||||
</span></span></span></code></pre></div><h2 id=tomlfindstdoptionalt><code>toml::find<std::optional<T>></code>
|
||||
<a class=anchor href=#tomlfindstdoptionalt>#</a></h2><p>If <code>std::optional</code> is available, you can specify <code>std::optional</code> as a template argument of <code>toml::find</code>.</p><p>Recursive access is also supported.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> input <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse_str(R<span style=color:#e6db74>"(</span>
|
||||
</span></span><span style=display:flex><span>integer <span style=color:#f92672>=</span> <span style=color:#ae81ff>1</span>
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span>[table]
|
||||
</span></span><span style=display:flex><span>key <span style=color:#f92672>=</span> <span style=color:#ae81ff>2</span>
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span><span style=color:#a6e22e>[[array-of-tables]]</span>
|
||||
</span></span><span style=display:flex><span>key <span style=color:#f92672>=</span> <span style=color:#ae81ff>3</span>
|
||||
</span></span><span style=display:flex><span>)<span style=color:#e6db74>");</span>
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>optional<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>>></span>(input, <span style=color:#e6db74>"integer"</span>);
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> b <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>optional<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>>></span>(input, <span style=color:#e6db74>"table"</span>, <span style=color:#e6db74>"key"</span>);
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> c <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>optional<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>>></span>(input, <span style=color:#e6db74>"array-of-tables"</span>, <span style=color:#ae81ff>0</span>, <span style=color:#e6db74>"key"</span>);
|
||||
</span></span></code></pre></div><p>If a key does not exist, no exception is thrown, and <code>std::nullopt</code> is returned.</p><p>However, if a type conversion fails, or if you attempt to access a key on a value that is not a table, or an index on a value that is not an array, a <code>toml::type_error</code> is thrown.</p><h2 id=defining-conversions-for-user-defined-types>Defining Conversions for User-Defined Types
|
||||
<a class=anchor href=#defining-conversions-for-user-defined-types>#</a></h2><p>With <code>toml::get</code> and <code>toml::find</code>, you can use user-defined types by employing one of the following methods.</p><h3 id=defining-tomlfrom>Defining <code>toml::from</code>
|
||||
<a class=anchor href=#defining-tomlfrom>#</a></h3><p>In toml11, there is a <code>toml::from</code> type that supports conversions from user-defined types by specializing it as follows:</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>namespace</span> extlib
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>struct</span> <span style=color:#a6e22e>foo</span>
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>int</span> a;
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string b;
|
||||
</span></span><span style=display:flex><span>};
|
||||
</span></span><span style=display:flex><span>} <span style=color:#75715e>// extlib
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>namespace</span> toml
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>template</span><span style=color:#f92672><></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>struct</span> <span style=color:#a6e22e>from</span><span style=color:#f92672><</span>extlib<span style=color:#f92672>::</span>foo<span style=color:#f92672>></span>
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>static</span> extlib<span style=color:#f92672>::</span>foo from_toml(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>&</span> v)
|
||||
</span></span><span style=display:flex><span> {
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> extlib<span style=color:#f92672>::</span>foo{
|
||||
</span></span><span style=display:flex><span> toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>></span>(v, <span style=color:#e6db74>"a"</span>),
|
||||
</span></span><span style=display:flex><span> toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>string<span style=color:#f92672>></span>(v, <span style=color:#e6db74>"b"</span>)
|
||||
</span></span><span style=display:flex><span> };
|
||||
</span></span><span style=display:flex><span> }
|
||||
</span></span><span style=display:flex><span>};
|
||||
</span></span><span style=display:flex><span>} <span style=color:#75715e>// toml
|
||||
</span></span></span></code></pre></div><p>If you also want to support <code>toml::value</code> with a modified type configuration, do as follows:</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>namespace</span> extlib
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>struct</span> <span style=color:#a6e22e>foo</span>
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>int</span> a;
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string b;
|
||||
</span></span><span style=display:flex><span>};
|
||||
</span></span><span style=display:flex><span>} <span style=color:#75715e>// extlib
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>namespace</span> toml
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>template</span><span style=color:#f92672><></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>struct</span> <span style=color:#a6e22e>from</span><span style=color:#f92672><</span>extlib<span style=color:#f92672>::</span>foo<span style=color:#f92672>></span>
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>template</span><span style=color:#f92672><</span><span style=color:#66d9ef>typename</span> TC<span style=color:#f92672>></span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>static</span> extlib<span style=color:#f92672>::</span>foo from_toml(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>basic_value<span style=color:#f92672><</span>TC<span style=color:#f92672>>&</span> v)
|
||||
</span></span><span style=display:flex><span> {
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> extlib<span style=color:#f92672>::</span>foo{
|
||||
</span></span><span style=display:flex><span> toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>></span>(v, <span style=color:#e6db74>"a"</span>),
|
||||
</span></span><span style=display:flex><span> toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>string<span style=color:#f92672>></span>(v, <span style=color:#e6db74>"b"</span>)
|
||||
</span></span><span style=display:flex><span> };
|
||||
</span></span><span style=display:flex><span> }
|
||||
</span></span><span style=display:flex><span>};
|
||||
</span></span><span style=display:flex><span>} <span style=color:#75715e>// toml
|
||||
</span></span></span></code></pre></div><p>This definition can be automatically generated using <code>TOML11_DEFINE_CONVERSION_NON_INTRUSIVE</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>namespace</span> extlib
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>struct</span> <span style=color:#a6e22e>foo</span>
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>int</span> a;
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string b;
|
||||
</span></span><span style=display:flex><span>};
|
||||
</span></span><span style=display:flex><span>} <span style=color:#75715e>// extlib
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span>TOML11_DEFINE_CONVERSION_NON_INTRUSIVE(extlib<span style=color:#f92672>::</span>foo, a, b)
|
||||
</span></span></code></pre></div><p>Alternatively, you can use a reflection library. Refer to the sample in <code>example</code> using <code>boost-ext/reflect</code>.</p><h3 id=defining-a-from_toml-member-function>Defining a <code>from_toml</code> Member Function
|
||||
<a class=anchor href=#defining-a-from_toml-member-function>#</a></h3><p>You can also define a conversion by defining a <code>from_toml</code> member function.</p><p>When using this method, a default constructor is required.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>struct</span> <span style=color:#a6e22e>bar</span>
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>int</span> a;
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string b;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>void</span> <span style=color:#a6e22e>from_toml</span>(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>&</span> v)
|
||||
</span></span><span style=display:flex><span> {
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>this</span><span style=color:#f92672>-></span>a <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>></span>(v, <span style=color:#e6db74>"a"</span>);
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>this</span><span style=color:#f92672>-></span>b <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>string<span style=color:#f92672>></span>(v, <span style=color:#e6db74>"b"</span>);
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> ;
|
||||
</span></span><span style=display:flex><span> }
|
||||
</span></span><span style=display:flex><span>};
|
||||
</span></span></code></pre></div><p>If both are defined, <code>toml::from</code> takes precedence.</p><h3 id=constructor-accepting-tomlvalue>Constructor Accepting <code>toml::value</code>
|
||||
<a class=anchor href=#constructor-accepting-tomlvalue>#</a></h3><p>If there is a constructor that accepts <code>toml::value</code>, conversion via <code>toml::get</code> can be performed.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>struct</span> <span style=color:#a6e22e>baz</span>
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>explicit</span> <span style=color:#a6e22e>baz</span>(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>&</span> v)
|
||||
</span></span><span style=display:flex><span> <span style=color:#f92672>:</span> a(toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>></span>(v, <span style=color:#e6db74>"a"</span>)), b(toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>string<span style=color:#f92672>></span>(v, <span style=color:#e6db74>"b"</span>))
|
||||
</span></span><span style=display:flex><span> {}
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>int</span> a;
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string b;
|
||||
</span></span><span style=display:flex><span>};
|
||||
</span></span></code></pre></div><p>If both are defined, <code>toml::from</code> and <code>from_toml</code> take precedence.</p><h2 id=applying-functions-with-tomlvisit>Applying Functions with <code>toml::visit</code>
|
||||
<a class=anchor href=#applying-functions-with-tomlvisit>#</a></h2><p>If you have a function object that can be applied to all types stored in <code>toml::value</code>, you can directly call that function without type conversion using <code>toml::visit</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>struct</span> <span style=color:#a6e22e>type_name_of</span>
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string <span style=color:#66d9ef>operator</span>()(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>::</span>boolean_type <span style=color:#f92672>&</span>) <span style=color:#66d9ef>const</span> {<span style=color:#66d9ef>return</span> <span style=color:#e6db74>"boolean"</span>;}
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string <span style=color:#66d9ef>operator</span>()(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>::</span>integer_type <span style=color:#f92672>&</span>) <span style=color:#66d9ef>const</span> {<span style=color:#66d9ef>return</span> <span style=color:#e6db74>"integer"</span>;}
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string <span style=color:#66d9ef>operator</span>()(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>::</span>floating_type <span style=color:#f92672>&</span>) <span style=color:#66d9ef>const</span> {<span style=color:#66d9ef>return</span> <span style=color:#e6db74>"floating"</span>;}
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string <span style=color:#66d9ef>operator</span>()(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>::</span>string_type <span style=color:#f92672>&</span>) <span style=color:#66d9ef>const</span> {<span style=color:#66d9ef>return</span> <span style=color:#e6db74>"string"</span>;}
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string <span style=color:#66d9ef>operator</span>()(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>::</span>local_time_type <span style=color:#f92672>&</span>) <span style=color:#66d9ef>const</span> {<span style=color:#66d9ef>return</span> <span style=color:#e6db74>"local_time"</span>;}
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string <span style=color:#66d9ef>operator</span>()(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>::</span>local_date_type <span style=color:#f92672>&</span>) <span style=color:#66d9ef>const</span> {<span style=color:#66d9ef>return</span> <span style=color:#e6db74>"local_date"</span>;}
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string <span style=color:#66d9ef>operator</span>()(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>::</span>local_datetime_type <span style=color:#f92672>&</span>) <span style=color:#66d9ef>const</span> {<span style=color:#66d9ef>return</span> <span style=color:#e6db74>"local_datetime"</span>;}
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string <span style=color:#66d9ef>operator</span>()(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>::</span>offset_datetime_type<span style=color:#f92672>&</span>) <span style=color:#66d9ef>const</span> {<span style=color:#66d9ef>return</span> <span style=color:#e6db74>"offset_datetime"</span>;}
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string <span style=color:#66d9ef>operator</span>()(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>::</span>array_type <span style=color:#f92672>&</span>) <span style=color:#66d9ef>const</span> {<span style=color:#66d9ef>return</span> <span style=color:#e6db74>"array"</span>;}
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string <span style=color:#66d9ef>operator</span>()(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>::</span>table_type <span style=color:#f92672>&</span>) <span style=color:#66d9ef>const</span> {<span style=color:#66d9ef>return</span> <span style=color:#e6db74>"table"</span>;}
|
||||
</span></span><span style=display:flex><span>};
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v(<span style=color:#ae81ff>3.14</span>);
|
||||
</span></span><span style=display:flex><span>std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> toml<span style=color:#f92672>::</span>visit(type_name_of{}, v) <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl; <span style=color:#75715e>// floating
|
||||
</span></span></span></code></pre></div><h2 id=constructing-tomlvalue>Constructing <code>toml::value</code>
|
||||
<a class=anchor href=#constructing-tomlvalue>#</a></h2><p><code>toml::value</code> can be constructed not only internally by the parser but also in user code.</p><p>You can construct it by passing a type that is either the same as or convertible to the types stored in <code>toml::value</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v1(true);
|
||||
</span></span><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v2(<span style=color:#ae81ff>42</span>);
|
||||
</span></span><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v3(<span style=color:#ae81ff>3.14</span>);
|
||||
</span></span></code></pre></div><p>For arrays, you can use <code>toml::array</code>:</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v(toml<span style=color:#f92672>::</span>array{<span style=color:#ae81ff>1</span>, <span style=color:#ae81ff>2</span>, <span style=color:#ae81ff>3</span>});
|
||||
</span></span></code></pre></div><p>Alternatively, you can pass containers such as <code>std::vector</code> directly:</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> std<span style=color:#f92672>::</span>vector<span style=color:#f92672><</span>toml<span style=color:#f92672>::</span>value<span style=color:#f92672>></span> a{<span style=color:#ae81ff>1</span>,<span style=color:#ae81ff>2</span>,<span style=color:#ae81ff>3</span>};
|
||||
</span></span><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v(a);
|
||||
</span></span></code></pre></div><p>For tables, you can use <code>toml::table</code>:</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v(toml<span style=color:#f92672>::</span>table{{<span style=color:#e6db74>"foo"</span>, <span style=color:#ae81ff>1</span>}, {<span style=color:#e6db74>"bar"</span>, <span style=color:#ae81ff>2</span>}, {<span style=color:#e6db74>"baz"</span>, <span style=color:#ae81ff>3</span>}});
|
||||
</span></span></code></pre></div><p>Or pass containers such as <code>std::map</code> directly:</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> std<span style=color:#f92672>::</span>map<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>string, toml<span style=color:#f92672>::</span>value<span style=color:#f92672>></span> t{
|
||||
</span></span><span style=display:flex><span> {<span style=color:#e6db74>"foo"</span>, <span style=color:#ae81ff>1</span>}, {<span style=color:#e6db74>"bar"</span>, <span style=color:#ae81ff>2</span>}, {<span style=color:#e6db74>"baz"</span>, <span style=color:#ae81ff>3</span>}
|
||||
</span></span><span style=display:flex><span> }
|
||||
</span></span><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v(t);
|
||||
</span></span></code></pre></div><p>You can pass <code>format_info</code> and comments to the constructor.</p><p>The type of comments is <code>std::vector<std::string></code>.
|
||||
Each element corresponds to a line.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>integer_format_info fmt;
|
||||
</span></span><span style=display:flex><span>fmt.fmt <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>integer_format<span style=color:#f92672>::</span>hex;
|
||||
</span></span><span style=display:flex><span>fmt.spacer <span style=color:#f92672>=</span> <span style=color:#ae81ff>4</span>;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v1(<span style=color:#ae81ff>0xDEADBEEF</span>, fmt);
|
||||
</span></span><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v2(<span style=color:#ae81ff>0xC0FFEE</span>, fmt, {<span style=color:#e6db74>"hex value!"</span>});
|
||||
</span></span></code></pre></div><h2 id=converting-to-tomlvalue>Converting to <code>toml::value</code>
|
||||
<a class=anchor href=#converting-to-tomlvalue>#</a></h2><p>When constructing <code>toml::value</code> from user-defined types, you can customize the behavior by defining <code>toml::into</code> or <code>into_toml</code>.</p><p><code>toml::into</code> is particularly useful when converting types from other libraries.</p><h3 id=defining-tomlinto>Defining <code>toml::into</code>
|
||||
<a class=anchor href=#defining-tomlinto>#</a></h3><p>By specializing <code>toml::into</code>, you can enable conversions to <code>toml::value</code>.</p><p>This is useful for types from external libraries that do not provide a conversion to <code>toml::value</code>.</p><p>Since <code>toml::value</code> passes <code>type_config</code> during conversion, you need to accept the <code>template</code> argument of <code>basic_value</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>namespace</span> extlib
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>struct</span> <span style=color:#a6e22e>foo</span>
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>int</span> a;
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string b;
|
||||
</span></span><span style=display:flex><span>};
|
||||
</span></span><span style=display:flex><span>} <span style=color:#75715e>// extlib
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>template</span><span style=color:#f92672><></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>struct</span> <span style=color:#a6e22e>into</span><span style=color:#f92672><</span>extlib<span style=color:#f92672>::</span>foo<span style=color:#f92672>></span>
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>template</span><span style=color:#f92672><</span><span style=color:#66d9ef>typename</span> TC<span style=color:#f92672>></span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>static</span> toml<span style=color:#f92672>::</span>basic_value<span style=color:#f92672><</span>TC<span style=color:#f92672>></span> into_toml(<span style=color:#66d9ef>const</span> extlib<span style=color:#f92672>::</span>foo<span style=color:#f92672>&</span> f)
|
||||
</span></span><span style=display:flex><span> {
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> toml<span style=color:#f92672>::</span>basic_value<span style=color:#f92672><</span>TC<span style=color:#f92672>></span>(<span style=color:#66d9ef>typename</span> toml<span style=color:#f92672>::</span>basic_value<span style=color:#f92672><</span>TC<span style=color:#f92672>>::</span>table_type{{<span style=color:#e6db74>"a"</span>, f.a}, {<span style=color:#e6db74>"b"</span>, f.b}});
|
||||
</span></span><span style=display:flex><span> }
|
||||
</span></span><span style=display:flex><span>};
|
||||
</span></span></code></pre></div><h3 id=defining-into_toml-member-function>Defining <code>into_toml</code> Member Function
|
||||
<a class=anchor href=#defining-into_toml-member-function>#</a></h3><p>Similar to <code>from_toml</code>, you can define the conversion through a member function.</p><p>If <code>toml::into</code> is defined, it takes precedence.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>struct</span> <span style=color:#a6e22e>bar</span>
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>int</span> a;
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string b;
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>template</span><span style=color:#f92672><</span><span style=color:#66d9ef>typename</span> TC<span style=color:#f92672>></span>
|
||||
</span></span><span style=display:flex><span> toml<span style=color:#f92672>::</span>basic_value<span style=color:#f92672><</span>TC<span style=color:#f92672>></span> into_toml() <span style=color:#66d9ef>const</span>
|
||||
</span></span><span style=display:flex><span> {
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> toml<span style=color:#f92672>::</span>basic_value<span style=color:#f92672><</span>TC<span style=color:#f92672>></span>(<span style=color:#66d9ef>typename</span> toml<span style=color:#f92672>::</span>basic_value<span style=color:#f92672><</span>TC<span style=color:#f92672>>::</span>table_type{
|
||||
</span></span><span style=display:flex><span> {<span style=color:#e6db74>"a"</span>, <span style=color:#66d9ef>this</span><span style=color:#f92672>-></span>a}, {<span style=color:#e6db74>"b"</span>, <span style=color:#66d9ef>this</span><span style=color:#f92672>-></span>b}
|
||||
</span></span><span style=display:flex><span> });
|
||||
</span></span><span style=display:flex><span> }
|
||||
</span></span><span style=display:flex><span>};
|
||||
</span></span></code></pre></div><h1 id=checking-whether-a-value-has-been-accessed>Checking Whether a Value Has Been Accessed
|
||||
<a class=anchor href=#checking-whether-a-value-has-been-accessed>#</a></h1><p>When compiled with the <code>TOML11_ENABLE_ACCESS_CHECK</code> macro defined, the <code>toml::value</code> class gains an additional method: <code>bool accessed() const</code>.
|
||||
This allows you to check whether a value has been accessed after parsing.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-console data-lang=console><span style=display:flex><span>$ g++ -std<span style=color:#f92672>=</span>c++17 -O2 -DTOML11_ENABLE_ACCESS_CHECK -I/path/to/toml11/include main.cpp
|
||||
</span></span></code></pre></div><p>or</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-console data-lang=console><span style=display:flex><span>$ cmake -B ./build -DTOML11_ENABLE_ACCESS_CHECK<span style=color:#f92672>=</span>ON
|
||||
</span></span></code></pre></div><p>or</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cmake data-lang=cmake><span style=display:flex><span>CPMAddPackage(
|
||||
</span></span><span style=display:flex><span> <span style=color:#e6db74>NAME</span> <span style=color:#e6db74>toml11</span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#e6db74>GITHUB_REPOSITORY</span> <span style=color:#e6db74>"ToruNiina/toml11"</span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#e6db74>VERSION</span> <span style=color:#e6db74>4.4.0</span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#e6db74>OPTIONS</span> <span style=color:#e6db74>"CMAKE_CXX_STANDARD 17"</span> <span style=color:#e6db74>"TOML11_PRECOMPILE ON"</span> <span style=color:#e6db74>"TOML11_ENABLE_ACCESS_CHECK ON"</span>
|
||||
</span></span><span style=display:flex><span> )<span style=color:#960050;background-color:#1e0010>
|
||||
</span></span></span></code></pre></div><p>This feature allows users to implement code that warns about values defined in a table but never used.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><toml.hpp></span><span style=color:#75715e>
|
||||
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
||||
</span></span><span style=display:flex><span><span style=color:#66d9ef>namespace</span> yours
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span>Config <span style=color:#a6e22e>read_config</span>(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>&</span> input)
|
||||
</span></span><span style=display:flex><span>{
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> cfg <span style=color:#f92672>=</span> read_your_config(input);
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>for</span> (<span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span><span style=color:#f92672>&</span> [k, v] <span style=color:#f92672>:</span> input.as_table())
|
||||
</span></span><span style=display:flex><span> {
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>if</span> (<span style=color:#f92672>!</span>v.accessed())
|
||||
</span></span><span style=display:flex><span> {
|
||||
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cerr <span style=color:#f92672><<</span> toml<span style=color:#f92672>::</span>format_error(<span style=color:#e6db74>"value defined but not used"</span>,
|
||||
</span></span><span style=display:flex><span> v.source_location(), <span style=color:#e6db74>"not used"</span>);
|
||||
</span></span><span style=display:flex><span> }
|
||||
</span></span><span style=display:flex><span> }
|
||||
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> cfg;
|
||||
</span></span><span style=display:flex><span>}
|
||||
</span></span><span style=display:flex><span>} <span style=color:#75715e>// namespace yours
|
||||
</span></span></span></code></pre></div><p>This feature is useful when a value is mistakenly defined under the wrong name but is never accessed. For example:</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#75715e># The correct key is "reactions"</span>
|
||||
</span></span><span style=display:flex><span><span style=color:#75715e># reactions = [ ":+1:", "star" ]</span>
|
||||
</span></span><span style=display:flex><span>
|
||||
</span></span><span style=display:flex><span><span style=color:#75715e># This key is incorrect and will not be read</span>
|
||||
</span></span><span style=display:flex><span><span style=color:#a6e22e>reaction</span> = [ <span style=color:#e6db74>":+1:"</span>, <span style=color:#e6db74>"star"</span> ]
|
||||
</span></span></code></pre></div><p>If this file is read using the above code, <code>read_your_config</code> will search for <code>reactions</code>. Since it is not defined, it will process <code>reactions</code> as an empty array.
|
||||
In this case, <code>input.at("reaction").accessed()</code> will be <code>false</code>, allowing it to be detected as an error.</p></article><footer class=book-footer><div class="flex flex-wrap justify-between"></div><script>(function(){function e(e){const t=window.getSelection(),n=document.createRange();n.selectNodeContents(e),t.removeAllRanges(),t.addRange(n)}document.querySelectorAll("pre code").forEach(t=>{t.addEventListener("click",function(){if(window.getSelection().toString())return;e(t.parentElement),navigator.clipboard&&navigator.clipboard.writeText(t.parentElement.textContent)})})})()</script></footer><label for=menu-control class="hidden book-menu-overlay"></label></div><aside class=book-toc><div class=book-toc-content><nav id=TableOfContents><ul><li><a href=#retrieving-values>Retrieving Values</a><ul><li><a href=#accessing-values-using-member-functions>Accessing Values Using Member Functions</a><ul><li><a href=#is_something-and-as_something><code>is_something</code> and <code>as_something</code></a></li><li><a href=#tomlvalue_t><code>toml::value_t</code></a></li><li><a href=#at--contains-size-push_back-emplace_back><code>at</code>, <code>[]</code>, <code>contains</code>, <code>size</code>, <code>push_back</code>, <code>emplace_back</code></a></li></ul></li><li><a href=#accessing-comments>Accessing Comments</a></li><li><a href=#handling-inline-tables-and-dotted-keys>Handling Inline Tables and Dotted Keys</a></li><li><a href=#handling-date-and-time-information>Handling Date and Time Information</a></li><li><a href=#converting-using-tomlgett>Converting Using <code>toml::get<T></code></a><ul><li><a href=#simple-conversions>Simple Conversions</a></li><li><a href=#conditions-for-obtaining-references>Conditions for Obtaining References</a></li><li><a href=#converting-arrays-to-stl-containers>Converting Arrays to STL Containers</a></li><li><a href=#converting-arrays-to-stdpair-or-stdtuple>Converting Arrays to <code>std::pair</code> or <code>std::tuple</code></a></li><li><a href=#converting-nested-arrays>Converting Nested Arrays</a></li><li><a href=#converting-tables-to-stdmap>Converting Tables to <code>std::map</code></a></li></ul></li><li><a href=#using-tomlget_or-to-specify-a-value-on-failure>Using <code>toml::get_or</code> to Specify a Value on Failure</a></li><li><a href=#using-tomlfindt-to-search-and-convert-simultaneously>Using <code>toml::find<T></code> to Search and Convert Simultaneously</a></li><li><a href=#using-tomlfind_or-to-search-and-specify-a-value-on-failure>Using <code>toml::find_or</code> to Search and Specify a Value on Failure</a></li><li><a href=#using-tomlfind_or_default-to-search-and-use-the-default-value-on-failure>Using <code>toml::find_or_default</code> to Search and Use the Default Value on Failure</a></li><li><a href=#tomlfindstdoptionalt><code>toml::find<std::optional<T>></code></a></li><li><a href=#defining-conversions-for-user-defined-types>Defining Conversions for User-Defined Types</a><ul><li><a href=#defining-tomlfrom>Defining <code>toml::from</code></a></li><li><a href=#defining-a-from_toml-member-function>Defining a <code>from_toml</code> Member Function</a></li><li><a href=#constructor-accepting-tomlvalue>Constructor Accepting <code>toml::value</code></a></li></ul></li><li><a href=#applying-functions-with-tomlvisit>Applying Functions with <code>toml::visit</code></a></li><li><a href=#constructing-tomlvalue>Constructing <code>toml::value</code></a></li><li><a href=#converting-to-tomlvalue>Converting to <code>toml::value</code></a><ul><li><a href=#defining-tomlinto>Defining <code>toml::into</code></a></li><li><a href=#defining-into_toml-member-function>Defining <code>into_toml</code> Member Function</a></li></ul></li></ul></li><li><a href=#checking-whether-a-value-has-been-accessed>Checking Whether a Value Has Been Accessed</a></li></ul></nav></div></aside></main></body></html>
|
||||
Reference in New Issue
Block a user