edlang/toml_edit/index.html
2024-08-01 07:04:26 +00:00

48 lines
17 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="`toml_edit`"><title>toml_edit - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-46f98efaafac5295.ttf.woff2,FiraSans-Regular-018c141bf0843ffd.woff2,FiraSans-Medium-8f9a781e4970d388.woff2,SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2,SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../static.files/normalize-76eba96aa4d2e634.css"><link rel="stylesheet" href="../static.files/rustdoc-dd39b87e5fcfba68.css"><meta name="rustdoc-vars" data-root-path="../" data-static-root-path="../static.files/" data-current-crate="toml_edit" data-themes="" data-resource-suffix="" data-rustdoc-version="1.80.0 (051478957 2024-07-21)" data-channel="1.80.0" data-search-js="search-d52510db62a78183.js" data-settings-js="settings-4313503d2e1961c2.js" ><script src="../static.files/storage-118b08c4c78b968e.js"></script><script defer src="../crates.js"></script><script defer src="../static.files/main-20a3ad099b048cf2.js"></script><noscript><link rel="stylesheet" href="../static.files/noscript-df360f571f6edeae.css"></noscript><link rel="alternate icon" type="image/png" href="../static.files/favicon-32x32-422f7d1d52889060.png"><link rel="icon" type="image/svg+xml" href="../static.files/favicon-2c020d218678b618.svg"></head><body class="rustdoc mod crate"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle" title="show sidebar"></button></nav><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../toml_edit/index.html">toml_edit</a><span class="version">0.22.20</span></h2></div><div class="sidebar-elems"><ul class="block"><li><a id="all-types" href="all.html">All Items</a></li></ul><section><ul class="block"><li><a href="#modules">Modules</a></li><li><a href="#structs">Structs</a></li><li><a href="#enums">Enums</a></li><li><a href="#traits">Traits</a></li><li><a href="#functions">Functions</a></li><li><a href="#types">Type Aliases</a></li></ul></section></div></nav><div class="sidebar-resizer"></div><main><div class="width-limiter"><rustdoc-search></rustdoc-search><section id="main-content" class="content"><div class="main-heading"><h1>Crate <a class="mod" href="#">toml_edit</a><button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><span class="out-of-band"><a class="src" href="../src/toml_edit/lib.rs.html#1-143">source</a> · <button id="toggle-all-docs" title="collapse all docs">[<span>&#x2212;</span>]</button></span></div><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><h2 id="toml_edit"><a class="doc-anchor" href="#toml_edit">§</a><code>toml_edit</code></h2>
<p>This crate allows you to parse and modify toml
documents, while preserving comments, spaces <em>and
relative order</em> or items.</p>
<p>If you also need the ease of a more traditional API, see the <a href="https://docs.rs/toml/latest/toml/"><code>toml</code></a> crate.</p>
<h2 id="example"><a class="doc-anchor" href="#example">§</a>Example</h2>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>toml_edit::{DocumentMut, value};
<span class="kw">let </span>toml = <span class="string">r#"
"hello" = 'toml!' # comment
['a'.b]
"#</span>;
<span class="kw">let </span><span class="kw-2">mut </span>doc = toml.parse::&lt;DocumentMut&gt;().expect(<span class="string">"invalid doc"</span>);
<span class="macro">assert_eq!</span>(doc.to_string(), toml);
<span class="comment">// let's add a new key/value pair inside a.b: c = {d = "hello"}
</span>doc[<span class="string">"a"</span>][<span class="string">"b"</span>][<span class="string">"c"</span>][<span class="string">"d"</span>] = value(<span class="string">"hello"</span>);
<span class="comment">// autoformat inline table a.b.c: { d = "hello" }
</span>doc[<span class="string">"a"</span>][<span class="string">"b"</span>][<span class="string">"c"</span>].as_inline_table_mut().map(|t| t.fmt());
<span class="kw">let </span>expected = <span class="string">r#"
"hello" = 'toml!' # comment
['a'.b]
c = { d = "hello" }
"#</span>;
<span class="macro">assert_eq!</span>(doc.to_string(), expected);</code></pre></div>
<h3 id="controlling-formatting"><a class="doc-anchor" href="#controlling-formatting">§</a>Controlling formatting</h3>
<p>By default, values are created with default formatting</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span><span class="kw-2">mut </span>doc = toml_edit::DocumentMut::new();
doc[<span class="string">"foo"</span>] = toml_edit::value(<span class="string">"bar"</span>);
<span class="kw">let </span>expected = <span class="string">r#"foo = "bar"
"#</span>;
<span class="macro">assert_eq!</span>(doc.to_string(), expected);</code></pre></div>
<p>You can choose a custom TOML representation by parsing the value.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span><span class="kw-2">mut </span>doc = toml_edit::DocumentMut::new();
doc[<span class="string">"foo"</span>] = <span class="string">"'bar'"</span>.parse::&lt;toml_edit::Item&gt;().unwrap();
<span class="kw">let </span>expected = <span class="string">r#"foo = 'bar'
"#</span>;
<span class="macro">assert_eq!</span>(doc.to_string(), expected);</code></pre></div>
<h3 id="limitations"><a class="doc-anchor" href="#limitations">§</a>Limitations</h3>
<p>Things it does not preserve:</p>
<ul>
<li>Order of dotted keys, see <a href="https://github.com/toml-rs/toml/issues/163">issue</a>.</li>
</ul>
</div></details><h2 id="modules" class="section-header">Modules<a href="#modules" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="mod" href="de/index.html" title="mod toml_edit::de">de</a></div><div class="desc docblock-short">Deserializing TOML into Rust structures.</div></li><li><div class="item-name"><a class="mod" href="ser/index.html" title="mod toml_edit::ser">ser</a></div><div class="desc docblock-short">Serializing Rust structures into TOML.</div></li><li><div class="item-name"><a class="mod" href="visit/index.html" title="mod toml_edit::visit">visit</a></div><div class="desc docblock-short">Document tree traversal to walk a shared borrow of a document tree.</div></li><li><div class="item-name"><a class="mod" href="visit_mut/index.html" title="mod toml_edit::visit_mut">visit_mut</a></div><div class="desc docblock-short">Document tree traversal to mutate an exclusive borrow of a document tree in place.</div></li></ul><h2 id="structs" class="section-header">Structs<a href="#structs" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="struct" href="struct.Array.html" title="struct toml_edit::Array">Array</a></div><div class="desc docblock-short">Type representing a TOML array,
payload of the <code>Value::Array</code> variants value</div></li><li><div class="item-name"><a class="struct" href="struct.ArrayOfTables.html" title="struct toml_edit::ArrayOfTables">ArrayOfTables</a></div><div class="desc docblock-short">Type representing a TOML array of tables</div></li><li><div class="item-name"><a class="struct" href="struct.Date.html" title="struct toml_edit::Date">Date</a></div><div class="desc docblock-short">A parsed TOML date value</div></li><li><div class="item-name"><a class="struct" href="struct.Datetime.html" title="struct toml_edit::Datetime">Datetime</a></div><div class="desc docblock-short">A parsed TOML datetime value</div></li><li><div class="item-name"><a class="struct" href="struct.DatetimeParseError.html" title="struct toml_edit::DatetimeParseError">DatetimeParseError</a></div><div class="desc docblock-short">Error returned from parsing a <code>Datetime</code> in the <code>FromStr</code> implementation.</div></li><li><div class="item-name"><a class="struct" href="struct.Decor.html" title="struct toml_edit::Decor">Decor</a></div><div class="desc docblock-short">A prefix and suffix,</div></li><li><div class="item-name"><a class="struct" href="struct.DocumentMut.html" title="struct toml_edit::DocumentMut">DocumentMut</a></div><div class="desc docblock-short">Type representing a TOML document</div></li><li><div class="item-name"><a class="struct" href="struct.Formatted.html" title="struct toml_edit::Formatted">Formatted</a></div><div class="desc docblock-short">A value together with its <code>to_string</code> representation,
including surrounding it whitespaces and comments.</div></li><li><div class="item-name"><a class="struct" href="struct.ImDocument.html" title="struct toml_edit::ImDocument">ImDocument</a></div><div class="desc docblock-short">Type representing a parsed TOML document</div></li><li><div class="item-name"><a class="struct" href="struct.InlineOccupiedEntry.html" title="struct toml_edit::InlineOccupiedEntry">InlineOccupiedEntry</a></div><div class="desc docblock-short">A view into a single occupied location in a <code>IndexMap</code>.</div></li><li><div class="item-name"><a class="struct" href="struct.InlineTable.html" title="struct toml_edit::InlineTable">InlineTable</a></div><div class="desc docblock-short">Type representing a TOML inline table,
payload of the <code>Value::InlineTable</code> variant</div></li><li><div class="item-name"><a class="struct" href="struct.InlineVacantEntry.html" title="struct toml_edit::InlineVacantEntry">InlineVacantEntry</a></div><div class="desc docblock-short">A view into a single empty location in a <code>IndexMap</code>.</div></li><li><div class="item-name"><a class="struct" href="struct.InternalString.html" title="struct toml_edit::InternalString">InternalString</a></div><div class="desc docblock-short">Opaque string storage internal to <code>toml_edit</code></div></li><li><div class="item-name"><a class="struct" href="struct.Key.html" title="struct toml_edit::Key">Key</a></div><div class="desc docblock-short">Key as part of a Key/Value Pair or a table header.</div></li><li><div class="item-name"><a class="struct" href="struct.KeyMut.html" title="struct toml_edit::KeyMut">KeyMut</a></div><div class="desc docblock-short">A mutable reference to a <code>Key</code>s formatting</div></li><li><div class="item-name"><a class="struct" href="struct.OccupiedEntry.html" title="struct toml_edit::OccupiedEntry">OccupiedEntry</a></div><div class="desc docblock-short">A view into a single occupied location in a <code>IndexMap</code>.</div></li><li><div class="item-name"><a class="struct" href="struct.RawString.html" title="struct toml_edit::RawString">RawString</a></div><div class="desc docblock-short">Opaque string storage for raw TOML; internal to <code>toml_edit</code></div></li><li><div class="item-name"><a class="struct" href="struct.Repr.html" title="struct toml_edit::Repr">Repr</a></div><div class="desc docblock-short">TOML-encoded value</div></li><li><div class="item-name"><a class="struct" href="struct.Table.html" title="struct toml_edit::Table">Table</a></div><div class="desc docblock-short">Type representing a TOML non-inline table</div></li><li><div class="item-name"><a class="struct" href="struct.Time.html" title="struct toml_edit::Time">Time</a></div><div class="desc docblock-short">A parsed TOML time value</div></li><li><div class="item-name"><a class="struct" href="struct.TomlError.html" title="struct toml_edit::TomlError">TomlError</a></div><div class="desc docblock-short">Type representing a TOML parse error</div></li><li><div class="item-name"><a class="struct" href="struct.VacantEntry.html" title="struct toml_edit::VacantEntry">VacantEntry</a></div><div class="desc docblock-short">A view into a single empty location in a <code>IndexMap</code>.</div></li></ul><h2 id="enums" class="section-header">Enums<a href="#enums" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="enum" href="enum.Entry.html" title="enum toml_edit::Entry">Entry</a></div><div class="desc docblock-short">A view into a single location in a map, which may be vacant or occupied.</div></li><li><div class="item-name"><a class="enum" href="enum.InlineEntry.html" title="enum toml_edit::InlineEntry">InlineEntry</a></div><div class="desc docblock-short">A view into a single location in a map, which may be vacant or occupied.</div></li><li><div class="item-name"><a class="enum" href="enum.Item.html" title="enum toml_edit::Item">Item</a></div><div class="desc docblock-short">Type representing either a value, a table, an array of tables, or none.</div></li><li><div class="item-name"><a class="enum" href="enum.Offset.html" title="enum toml_edit::Offset">Offset</a></div><div class="desc docblock-short">A parsed TOML time offset</div></li><li><div class="item-name"><a class="enum" href="enum.Value.html" title="enum toml_edit::Value">Value</a></div><div class="desc docblock-short">Representation of a TOML Value (as part of a Key/Value Pair).</div></li></ul><h2 id="traits" class="section-header">Traits<a href="#traits" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="trait" href="trait.TableLike.html" title="trait toml_edit::TableLike">TableLike</a></div><div class="desc docblock-short">This trait represents either a <code>Table</code>, or an <code>InlineTable</code>.</div></li></ul><h2 id="functions" class="section-header">Functions<a href="#functions" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="fn" href="fn.array.html" title="fn toml_edit::array">array</a></div><div class="desc docblock-short">Returns an empty array of tables.</div></li><li><div class="item-name"><a class="fn" href="fn.table.html" title="fn toml_edit::table">table</a></div><div class="desc docblock-short">Returns an empty table.</div></li><li><div class="item-name"><a class="fn" href="fn.value.html" title="fn toml_edit::value">value</a></div><div class="desc docblock-short">Returns a formatted value.</div></li></ul><h2 id="types" class="section-header">Type Aliases<a href="#types" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="type" href="type.ArrayIntoIter.html" title="type toml_edit::ArrayIntoIter">ArrayIntoIter</a></div><div class="desc docblock-short">An owned iterator type over <code>Table</code>s key/value pairs.</div></li><li><div class="item-name"><a class="type" href="type.ArrayIter.html" title="type toml_edit::ArrayIter">ArrayIter</a></div><div class="desc docblock-short">An iterator type over <code>Array</code>s values.</div></li><li><div class="item-name"><a class="type" href="type.ArrayIterMut.html" title="type toml_edit::ArrayIterMut">ArrayIterMut</a></div><div class="desc docblock-short">An iterator type over <code>Array</code>s values.</div></li><li><div class="item-name"><a class="type" href="type.ArrayOfTablesIntoIter.html" title="type toml_edit::ArrayOfTablesIntoIter">ArrayOfTablesIntoIter</a></div><div class="desc docblock-short">An iterator type over <code>ArrayOfTables</code>s values.</div></li><li><div class="item-name"><a class="type" href="type.ArrayOfTablesIter.html" title="type toml_edit::ArrayOfTablesIter">ArrayOfTablesIter</a></div><div class="desc docblock-short">An iterator type over <code>ArrayOfTables</code>s values.</div></li><li><div class="item-name"><a class="type" href="type.ArrayOfTablesIterMut.html" title="type toml_edit::ArrayOfTablesIterMut">ArrayOfTablesIterMut</a></div><div class="desc docblock-short">An iterator type over <code>ArrayOfTables</code>s values.</div></li><li><div class="item-name"><a class="type" href="type.Document.html" title="type toml_edit::Document">Document</a><span class="stab deprecated" title="">Deprecated</span></div><div class="desc docblock-short">Deprecated, replaced with <a href="struct.DocumentMut.html" title="struct toml_edit::DocumentMut"><code>DocumentMut</code></a></div></li><li><div class="item-name"><a class="type" href="type.InlineTableIntoIter.html" title="type toml_edit::InlineTableIntoIter">InlineTableIntoIter</a></div><div class="desc docblock-short">An owned iterator type over key/value pairs of an inline table.</div></li><li><div class="item-name"><a class="type" href="type.InlineTableIter.html" title="type toml_edit::InlineTableIter">InlineTableIter</a></div><div class="desc docblock-short">An iterator type over key/value pairs of an inline table.</div></li><li><div class="item-name"><a class="type" href="type.InlineTableIterMut.html" title="type toml_edit::InlineTableIterMut">InlineTableIterMut</a></div><div class="desc docblock-short">A mutable iterator type over key/value pairs of an inline table.</div></li><li><div class="item-name"><a class="type" href="type.IntoIter.html" title="type toml_edit::IntoIter">IntoIter</a></div><div class="desc docblock-short">An owned iterator type over <code>Table</code>s key/value pairs.</div></li><li><div class="item-name"><a class="type" href="type.Iter.html" title="type toml_edit::Iter">Iter</a></div><div class="desc docblock-short">An iterator type over <code>Table</code>s key/value pairs.</div></li><li><div class="item-name"><a class="type" href="type.IterMut.html" title="type toml_edit::IterMut">IterMut</a></div><div class="desc docblock-short">A mutable iterator type over <code>Table</code>s key/value pairs.</div></li></ul></section></div></main></body></html>