toml_edit/
lib.rs

1#![deny(missing_docs)]
2// https://github.com/Marwes/combine/issues/172
3#![recursion_limit = "256"]
4
5//! # `toml_edit`
6//!
7//! This crate allows you to parse and modify toml
8//! documents, while preserving comments, spaces *and
9//! relative order* or items.
10//!
11//! If you also need the ease of a more traditional API, see the [`toml`] crate.
12//!
13//! # Example
14//!
15//! ```rust
16//! use toml_edit::{Document, value};
17//!
18//! let toml = r#"
19//! "hello" = 'toml!' # comment
20//! ['a'.b]
21//! "#;
22//! let mut doc = toml.parse::<Document>().expect("invalid doc");
23//! assert_eq!(doc.to_string(), toml);
24//! // let's add a new key/value pair inside a.b: c = {d = "hello"}
25//! doc["a"]["b"]["c"]["d"] = value("hello");
26//! // autoformat inline table a.b.c: { d = "hello" }
27//! doc["a"]["b"]["c"].as_inline_table_mut().map(|t| t.fmt());
28//! let expected = r#"
29//! "hello" = 'toml!' # comment
30//! ['a'.b]
31//! c = { d = "hello" }
32//! "#;
33//! assert_eq!(doc.to_string(), expected);
34//! ```
35//!
36//! ## Controlling formatting
37//!
38//! By default, values are created with default formatting
39//! ```rust
40//! let mut doc = toml_edit::Document::new();
41//! doc["foo"] = toml_edit::value("bar");
42//! let expected = r#"foo = "bar"
43//! "#;
44//! assert_eq!(doc.to_string(), expected);
45//! ```
46//!
47//! You can choose a custom TOML representation by parsing the value.
48//! ```rust
49//! let mut doc = toml_edit::Document::new();
50//! doc["foo"] = "'bar'".parse::<toml_edit::Item>().unwrap();
51//! let expected = r#"foo = 'bar'
52//! "#;
53//! assert_eq!(doc.to_string(), expected);
54//! ```
55//!
56//! ## Limitations
57//!
58//! Things it does not preserve:
59//!
60//! * Scattered array of tables (tables are reordered by default, see [test]).
61//! * Order of dotted keys, see [issue](https://github.com/ordian/toml_edit/issues/163).
62//!
63//! [`toml`]: https://docs.rs/toml/latest/toml/
64//! [test]: https://github.com/ordian/toml_edit/blob/f09bd5d075fdb7d2ef8d9bb3270a34506c276753/tests/test_valid.rs#L84
65
66mod array;
67mod array_of_tables;
68mod document;
69mod encode;
70mod index;
71mod inline_table;
72mod internal_string;
73mod item;
74mod key;
75mod parser;
76mod raw_string;
77mod repr;
78mod table;
79mod value;
80
81#[cfg(feature = "easy")]
82pub mod easy;
83
84#[cfg(feature = "serde")]
85pub mod de;
86#[cfg(feature = "serde")]
87pub mod ser;
88
89pub mod visit;
90pub mod visit_mut;
91
92pub use crate::array::{Array, ArrayIntoIter, ArrayIter, ArrayIterMut};
93pub use crate::array_of_tables::{
94    ArrayOfTables, ArrayOfTablesIntoIter, ArrayOfTablesIter, ArrayOfTablesIterMut,
95};
96pub use crate::document::Document;
97pub use crate::inline_table::{
98    InlineEntry, InlineOccupiedEntry, InlineTable, InlineTableIntoIter, InlineTableIter,
99    InlineTableIterMut, InlineVacantEntry,
100};
101pub use crate::internal_string::InternalString;
102pub use crate::item::{array, table, value, Item};
103pub use crate::key::{Key, KeyMut};
104pub use crate::parser::TomlError;
105pub use crate::raw_string::RawString;
106pub use crate::repr::{Decor, Formatted, Repr};
107pub use crate::table::{
108    Entry, IntoIter, Iter, IterMut, OccupiedEntry, Table, TableLike, VacantEntry,
109};
110pub use crate::value::Value;
111pub use toml_datetime::*;
112
113// Prevent users from some traits.
114pub(crate) mod private {
115    pub trait Sealed {}
116    impl Sealed for usize {}
117    impl Sealed for str {}
118    impl Sealed for String {}
119    impl Sealed for i64 {}
120    impl Sealed for f64 {}
121    impl Sealed for bool {}
122    impl Sealed for crate::Datetime {}
123    impl<'a, T: ?Sized> Sealed for &'a T where T: Sealed {}
124    impl Sealed for crate::Table {}
125    impl Sealed for crate::InlineTable {}
126}
toml_edit/lib.rs

toml_edit/
lib.rs
