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 | |
67 | mod array; |
68 | mod array_of_tables; |
69 | mod document; |
70 | mod encode; |
71 | mod index; |
72 | mod inline_table; |
73 | mod internal_string; |
74 | mod item; |
75 | mod key; |
76 | mod parser; |
77 | mod raw_string; |
78 | mod repr; |
79 | mod table; |
80 | mod value; |
81 | |
82 | #[cfg (feature = "serde" )] |
83 | pub mod de; |
84 | #[cfg (feature = "serde" )] |
85 | pub mod ser; |
86 | |
87 | pub mod visit; |
88 | pub mod visit_mut; |
89 | |
90 | pub use crate::array::{Array, ArrayIntoIter, ArrayIter, ArrayIterMut}; |
91 | pub use crate::array_of_tables::{ |
92 | ArrayOfTables, ArrayOfTablesIntoIter, ArrayOfTablesIter, ArrayOfTablesIterMut, |
93 | }; |
94 | pub use crate::document::Document; |
95 | pub use crate::inline_table::{ |
96 | InlineEntry, InlineOccupiedEntry, InlineTable, InlineTableIntoIter, InlineTableIter, |
97 | InlineTableIterMut, InlineVacantEntry, |
98 | }; |
99 | pub use crate::internal_string::InternalString; |
100 | pub use crate::item::{array, table, value, Item}; |
101 | pub use crate::key::{Key, KeyMut}; |
102 | pub use crate::parser::TomlError; |
103 | pub use crate::raw_string::RawString; |
104 | pub use crate::repr::{Decor, Formatted, Repr}; |
105 | pub use crate::table::{ |
106 | Entry, IntoIter, Iter, IterMut, OccupiedEntry, Table, TableLike, VacantEntry, |
107 | }; |
108 | pub use crate::value::Value; |
109 | pub use toml_datetime::*; |
110 | |
111 | // Prevent users from some traits. |
112 | pub(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 | |