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