# features on toml11

https://toruniina.github.io/toml11/docs/features/ Recent content in features on toml11 Hugo en

# parsing files

https://toruniina.github.io/toml11/docs/features/parsing_files/ Mon, 01 Jan 0001 00:00:00 +0000 https://toruniina.github.io/toml11/docs/features/parsing_files/<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>

# getting values

https://toruniina.github.io/toml11/docs/features/value/ Mon, 01 Jan 0001 00:00:00 +0000 https://toruniina.github.io/toml11/docs/features/value/<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>

# error message

https://toruniina.github.io/toml11/docs/features/error_message/ Mon, 01 Jan 0001 00:00:00 +0000 https://toruniina.github.io/toml11/docs/features/error_message/<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>

# serializing values

https://toruniina.github.io/toml11/docs/features/serialize/ Mon, 01 Jan 0001 00:00:00 +0000 https://toruniina.github.io/toml11/docs/features/serialize/<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>

# configuring types

https://toruniina.github.io/toml11/docs/features/configure_types/ Mon, 01 Jan 0001 00:00:00 +0000 https://toruniina.github.io/toml11/docs/features/configure_types/<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>

# toml literal

https://toruniina.github.io/toml11/docs/features/literal/ Mon, 01 Jan 0001 00:00:00 +0000 https://toruniina.github.io/toml11/docs/features/literal/<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>

# toml spec

https://toruniina.github.io/toml11/docs/features/toml_spec/ Mon, 01 Jan 0001 00:00:00 +0000 https://toruniina.github.io/toml11/docs/features/toml_spec/<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>

# extension

https://toruniina.github.io/toml11/docs/features/extension/ Mon, 01 Jan 0001 00:00:00 +0000 https://toruniina.github.io/toml11/docs/features/extension/<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>