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