mirror of
https://github.com/ToruNiina/toml11.git
synced 2025-09-17 09:08:08 +08:00
135 lines
19 KiB
XML
135 lines
19 KiB
XML
<?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> |