zhangyiss/toml11
1
0
Fork 0
mirror of https://github.com/ToruNiina/toml11.git synced 2025-12-16 03:08:52 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity
Files
gh-pages
toml11/docs/features/extension/index.html
ToruNiina 360850a8c8 Merge pull request #295 from franzpoeschel/undef-source-location 
Add a way to optionally suppress usage of std::source_location b96acf96ba
2025-12-03 15:01:09 +00:00

72 lines
17 KiB
HTML
Raw Permalink Blame History

<!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.6d8037b375fe949eee1b70501c5fb9478914c9c5eb3ef7696163fd3031c69421.css integrity="sha256-bYA3s3X+lJ7uG3BQHF+5R4kUycXrPvdpYWP9MDHGlCE=" crossorigin=anonymous><script defer src=/toml11/fuse.min.js></script><script defer src=/toml11/en.search.min.87bec23503963d7026bfa3a917b92707789d315c9c9e005e23226b35dce643f5.js integrity="sha256-h77CNQOWPXAmv6OpF7knB3idMVycngBeIyJrNdzmQ/U=" 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>&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></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>&#34;a = null&#34;</span>, spec);
</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>).is_empty());
</span></span><span style=display:flex><span> assert(v.at(<span style=color:#e6db74>&#34;a&#34;</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>&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></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>&#34;a = 0x1.91eb851eb851fp+1&#34;</span>, spec);
</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>).is_floating());
</span></span><span style=display:flex><span> assert(v.at(<span style=color:#e6db74>&#34;a&#34;</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>&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></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>&#34;a = 86_400_sec&#34;</span>, spec);
</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>).is_integer());
</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>86400</span>);
</span></span><span style=display:flex><span> assert(v.at(<span style=color:#e6db74>&#34;a&#34;</span>).as_integer_fmt().suffix <span style=color:#f92672>==</span> <span style=color:#e6db74>&#34;sec&#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></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>
Reference in New Issue View Git Blame Copy Permalink