saneyaml/
lib.rs

1//! Pure-Rust YAML parser, emitter, and Serde integration for
2//! configuration-shaped YAML.
3//!
4//! The preview API focuses on YAML 1.2 parser events, pull-based event and
5//! document streaming, loaded document trees with default merge-key expansion,
6//! explicit and directive-driven YAML 1.1 scalar construction options, `serde_yaml`-style
7//! `Value`/`Mapping`/`Number` workflows, typed Serde reads, structural writes,
8//! explicit emission fidelity tiers, and line/column diagnostics. See
9//! `docs/MIGRATION.md` and `docs/COMPATIBILITY.md` for the current adoption
10//! contract and intentional non-goals.
11//!
12//! ```rust
13//! use serde::Deserialize;
14//!
15//! #[derive(Deserialize)]
16//! struct Config {
17//!     name: String,
18//! }
19//!
20//! let config: Config = saneyaml::from_str("name: api\n")?;
21//! assert_eq!(config.name, "api");
22//! # Ok::<(), saneyaml::Error>(())
23//! ```
24//!
25#![forbid(unsafe_code)]
26
27mod ast;
28mod de;
29mod emit;
30mod error;
31#[cfg(any(test, feature = "bench-internals"))]
32mod event_de;
33mod key_identity;
34#[cfg(feature = "lossless")]
35pub mod lossless;
36mod parse;
37mod schema;
38mod ser;
39mod yaml11;
40
41/// Serde helper modules matching selected `serde_yaml::with` paths.
42pub mod with;
43
44/// Pull-based YAML event and document streaming APIs.
45pub mod stream {
46    pub use crate::parse::{DocumentStream, EventStream};
47}
48
49#[cfg(feature = "bench-internals")]
50#[doc(hidden)]
51pub mod __unstable_event_serde {
52    use std::io::Read;
53
54    use crate::{LoadOptions, Result};
55
56    pub fn from_documents_str<T>(input: &str) -> Result<Vec<T>>
57    where
58        T: serde::de::DeserializeOwned,
59    {
60        from_documents_str_with_options(input, LoadOptions::new())
61    }
62
63    pub fn from_documents_str_with_options<T>(input: &str, options: LoadOptions) -> Result<Vec<T>>
64    where
65        T: serde::de::DeserializeOwned,
66    {
67        crate::event_de::from_documents_str_with_options(input, options)
68    }
69
70    pub fn from_documents_reader<T, R>(reader: R) -> Result<Vec<T>>
71    where
72        T: serde::de::DeserializeOwned,
73        R: Read,
74    {
75        from_documents_reader_with_options(reader, LoadOptions::new())
76    }
77
78    pub fn from_documents_reader_with_options<T, R>(
79        reader: R,
80        options: LoadOptions,
81    ) -> Result<Vec<T>>
82    where
83        T: serde::de::DeserializeOwned,
84        R: Read,
85    {
86        crate::event_de::document_iter_reader_with_options(reader, options)?.collect()
87    }
88}
89
90/// Mapping types and iterators for YAML [`Mapping`].
91pub mod mapping {
92    pub use crate::ast::{
93        Entry, IntoIter, IntoKeys, IntoValues, Iter, IterMut, Keys, Mapping, MappingIndex as Index,
94        OccupiedEntry, VacantEntry, Values, ValuesMut,
95    };
96}
97
98/// Value-oriented API matching the `serde_yaml::value` module shape.
99pub mod value {
100    pub use crate::ast::{
101        Date, Index, Mapping, Number, Sequence, Tag, TaggedValue, Time, TimeZoneOffset, Timestamp,
102        Value,
103    };
104    pub use crate::de::from_value;
105    pub use crate::ser::{ValueSerializer as Serializer, to_value};
106}
107
108pub use ast::{
109    BorrowedNode, BorrowedNodeValue, BorrowedTaggedNode, Date, Entry, Index, Mapping, Node,
110    NodeValue, Number, OccupiedEntry, ScalarSource, Sequence, Tag, TaggedNode, TaggedValue, Time,
111    TimeZoneOffset, Timestamp, VacantEntry, Value,
112};
113pub use de::{
114    Deserializer, from_documents_reader, from_documents_slice, from_documents_str, from_node,
115    from_reader, from_slice, from_str, from_value,
116};
117pub use emit::{
118    BlockScalarStyle, EmitCollectionStyle, EmitFidelity, EmitOptions, EnumRepresentation, KeyOrder,
119    ScalarQuoteStyle,
120};
121pub use error::{
122    Diagnostic, Error, ErrorCategory, ErrorPath, ErrorPathSegment, Location, RelatedDiagnostic,
123    Result, SourceDiagnostic, SourceRenderOptions, Span,
124};
125#[cfg(feature = "lossless")]
126pub use lossless::{
127    AliasId, AnchorId, ConfigEditor, ConfigPath, LosslessAlias, LosslessAnchor, LosslessDocument,
128    LosslessEdit, LosslessEffectiveMappingEntry, LosslessEffectiveMappingSource, LosslessNode,
129    LosslessNodeKind, LosslessStream, LosslessTrivia, LosslessTriviaKind, NodeId, PathSegment,
130    edit, edit_file, parse_lossless, parse_lossless_bytes, parse_lossless_bytes_with_options,
131    parse_lossless_with_options,
132};
133pub use parse::{
134    CollectionStyle, DocumentStream, Event, EventAnchor, EventDocumentDirectives, EventMeta,
135    EventStream, EventTag, EventTagDirective, EventYamlVersion, ScalarStyle,
136    parse_borrowed_documents, parse_bytes, parse_documents, parse_events, parse_str,
137    stream_documents, stream_documents_reader, stream_documents_slice, stream_events,
138    stream_events_reader, stream_events_slice,
139};
140pub use schema::{
141    DEFAULT_ALIAS_EXPANSION_FACTOR, DEFAULT_MAX_COLLECTION_ITEMS, DEFAULT_MAX_INPUT_BYTES,
142    DEFAULT_MAX_NESTING_DEPTH, DEFAULT_MAX_SCALAR_BYTES, DEFAULT_MIN_ALIAS_EXPANSION_NODES,
143    LoadOptions, Schema,
144};
145pub use ser::{
146    Serializer, to_string, to_string_with_options, to_value, to_writer, to_writer_with_options,
147};
saneyaml/lib.rs

saneyaml/
lib.rs
