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  //! # #[cfg(feature = "parse")] {
18  //! # #[cfg(feature = "display")] {
19  //! use toml_edit::{Document, value};
20  //!
21  //! let toml = r#"
22  //! "hello" = 'toml!' # comment
23  //! ['a'.b]
24  //! "#;
25  //! let mut doc = toml.parse::<Document>().expect("invalid doc");
26  //! assert_eq!(doc.to_string(), toml);
27  //! // let's add a new key/value pair inside a.b: c = {d = "hello"}
28  //! doc["a"]["b"]["c"]["d"] = value("hello");
29  //! // autoformat inline table a.b.c: { d = "hello" }
30  //! doc["a"]["b"]["c"].as_inline_table_mut().map(|t| t.fmt());
31  //! let expected = r#"
32  //! "hello" = 'toml!' # comment
33  //! ['a'.b]
34  //! c = { d = "hello" }
35  //! "#;
36  //! assert_eq!(doc.to_string(), expected);
37  //! # }
38  //! # }
39  //! ```
40  //!
41  //! ## Controlling formatting
42  //!
43  //! By default, values are created with default formatting
44  //! ```rust
45  //! # #[cfg(feature = "display")] {
46  //! let mut doc = toml_edit::Document::new();
47  //! doc["foo"] = toml_edit::value("bar");
48  //! let expected = r#"foo = "bar"
49  //! "#;
50  //! assert_eq!(doc.to_string(), expected);
51  //! # }
52  //! ```
53  //!
54  //! You can choose a custom TOML representation by parsing the value.
55  //! ```rust
56  //! # #[cfg(feature = "display")] {
57  //! let mut doc = toml_edit::Document::new();
58  //! doc["foo"] = "'bar'".parse::<toml_edit::Item>().unwrap();
59  //! let expected = r#"foo = 'bar'
60  //! "#;
61  //! assert_eq!(doc.to_string(), expected);
62  //! # }
63  //! ```
64  //!
65  //! ## Limitations
66  //!
67  //! Things it does not preserve:
68  //!
69  //! * Order of dotted keys, see [issue](https://github.com/toml-rs/toml/issues/163).
70  //!
71  //! [`toml`]: https://docs.rs/toml/latest/toml/
72  
73  mod array;
74  mod array_of_tables;
75  mod document;
76  #[cfg(feature = "display")]
77  mod encode;
78  mod error;
79  mod index;
80  mod inline_table;
81  mod internal_string;
82  mod item;
83  mod key;
84  #[cfg(feature = "parse")]
85  mod parser;
86  mod raw_string;
87  mod repr;
88  mod table;
89  mod value;
90  
91  #[cfg(feature = "serde")]
92  pub mod de;
93  #[cfg(feature = "serde")]
94  pub mod ser;
95  
96  pub mod visit;
97  pub mod visit_mut;
98  
99  pub use crate::array::{Array, ArrayIntoIter, ArrayIter, ArrayIterMut};
100  pub use crate::array_of_tables::{
101      ArrayOfTables, ArrayOfTablesIntoIter, ArrayOfTablesIter, ArrayOfTablesIterMut,
102  };
103  pub use crate::document::Document;
104  pub use crate::error::TomlError;
105  pub use crate::inline_table::{
106      InlineEntry, InlineOccupiedEntry, InlineTable, InlineTableIntoIter, InlineTableIter,
107      InlineTableIterMut, InlineVacantEntry,
108  };
109  pub use crate::internal_string::InternalString;
110  pub use crate::item::{array, table, value, Item};
111  pub use crate::key::{Key, KeyMut};
112  pub use crate::raw_string::RawString;
113  pub use crate::repr::{Decor, Formatted, Repr};
114  pub use crate::table::{
115      Entry, IntoIter, Iter, IterMut, OccupiedEntry, Table, TableLike, VacantEntry,
116  };
117  pub use crate::value::Value;
118  pub use toml_datetime::*;
119  
120  // Prevent users from some traits.
121  pub(crate) mod private {
122      pub trait Sealed {}
123      impl Sealed for usize {}
124      impl Sealed for str {}
125      impl Sealed for String {}
126      impl Sealed for i64 {}
127      impl Sealed for f64 {}
128      impl Sealed for bool {}
129      impl Sealed for crate::Datetime {}
130      impl<'a, T: ?Sized> Sealed for &'a T where T: Sealed {}
131      impl Sealed for crate::Table {}
132      impl Sealed for crate::InlineTable {}
133  }
134