toml_write/lib.rs
1//! A low-level interface for writing out TOML
2//!
3//! Considerations when serializing arbitrary data:
4//! - Verify the implementation with [`toml-test-harness`](https://docs.rs/toml-test-harness)
5//! - Be sure to group keys under a table before writing another table
6//! - Watch for extra trailing newlines and leading newlines, both when starting with top-level
7//! keys or a table
8//! - When serializing an array-of-tables, be sure to verify that all elements of the array
9//! serialize as tables
10//! - Standard tables and inline tables may need separate implementations of corner cases,
11//! requiring verifying them both
12//!
13//! When serializing Rust data structures
14//! - `Option`: Skip key-value pairs with a value of `None`, otherwise error when seeing `None`
15//! - When skipping key-value pairs, be careful that a deeply nested `None` doesn't get skipped
16//! - Scalars and arrays are unsupported as top-level data types
17//! - Tuples and tuple variants seriallize as arrays
18//! - Structs, struct variants, and maps serialize as tables
19//! - Newtype variants serialize as to the inner type
20//! - Unit variants serialize to a string
21//! - Unit and unit structs don't have a clear meaning in TOML
22//!
23//! # Example
24//!
25//! ```rust
26//! use toml_write::TomlWrite as _;
27//!
28//! # fn main() -> std::fmt::Result {
29//! let mut output = String::new();
30//! output.newline()?;
31//! output.open_table_header()?;
32//! output.key("table")?;
33//! output.close_table_header()?;
34//! output.newline()?;
35//!
36//! output.key("key")?;
37//! output.space()?;
38//! output.keyval_sep()?;
39//! output.space()?;
40//! output.value("value")?;
41//! output.newline()?;
42//!
43//! assert_eq!(output, r#"
44//! [table]
45//! key = "value"
46//! "#);
47//! # Ok(())
48//! # }
49//! ```
50
51#![cfg_attr(all(not(feature = "std"), not(test)), no_std)]
52#![cfg_attr(docsrs, feature(doc_auto_cfg))]
53#![forbid(unsafe_code)]
54#![warn(clippy::std_instead_of_core)]
55#![warn(clippy::std_instead_of_alloc)]
56#![warn(clippy::print_stderr)]
57#![warn(clippy::print_stdout)]
58
59#[cfg(feature = "alloc")]
60extern crate alloc;
61
62mod key;
63mod string;
64mod value;
65mod write;
66
67#[cfg(feature = "alloc")]
68pub use key::ToTomlKey;
69pub use key::WriteTomlKey;
70pub use string::TomlKey;
71pub use string::TomlKeyBuilder;
72pub use string::TomlString;
73pub use string::TomlStringBuilder;
74#[cfg(feature = "alloc")]
75pub use value::ToTomlValue;
76pub use value::WriteTomlValue;
77pub use write::TomlWrite;