toml_edit/
lib.rs

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

toml_edit/
lib.rs
