deser_core/lib.rs
1//! The core of [deser](https://docs.rs/deser).
2//!
3//! This crate is an implementation detail of deser, use the
4//! [`deser`](https://docs.rs/deser) crate instead which re-exports
5//! everything in here together with the derive macros. The crates of the
6//! data formats depend on this crate so that they can be compiled without
7//! waiting for the derive macros.
8#![doc(html_logo_url = "https://raw.githubusercontent.com/mitsuhiko/deser/main/artwork/logo.svg")]
9#![cfg_attr(docsrs, feature(doc_cfg))]
10#![cfg_attr(not(any(feature = "std", test)), no_std)]
11
12extern crate alloc;
13
14#[macro_use]
15mod macros;
16mod event;
17
18mod adapted;
19
20pub mod adapters;
21mod arena;
22pub mod de;
23mod error;
24pub mod ext;
25pub mod hints;
26#[cfg(feature = "io")]
27pub mod io;
28pub mod ser;
29pub mod stream;
30
31mod bytes_format;
32mod context;
33mod extensions;
34mod foreign_impls;
35#[cfg(feature = "open-enums")]
36mod open_enum;
37mod position;
38mod source;
39mod state;
40mod std_impls;
41#[cfg(feature = "std")]
42mod std_only_impls;
43mod sync;
44mod text;
45mod unwind;
46
47pub use self::bytes_format::BytesFormat;
48pub use self::context::Context;
49pub use self::error::{Error, ErrorAttachment, ErrorCategory, ErrorContext, ErrorKind};
50pub use self::event::{Atom, Bytes, ContainerShape, Event, Implicit, ImplicitValue, Order};
51pub use self::extensions::EventData;
52#[cfg(feature = "open-enums")]
53pub use self::open_enum::{OpenEnum, OpenEnums, OpenVariant};
54pub use self::position::Position;
55pub use self::source::{Source, TrackLocations};
56pub use self::state::State;
57pub use self::text::Text;
58
59// common re-exports
60
61#[doc(no_inline)]
62pub use self::{de::Deserialize, ser::Serialize, stream::Streamed};
63
64#[cfg(feature = "derive")]
65pub mod derive;
66
67// # API Conventions
68//
69// The crates of deser follow these rules (and so should new APIs):
70//
71// * Values are changed with setters, `set_x(&mut self, value)` (a
72// `const fn` where possible), and read with getters named after the
73// value (`x(&self)`). Types have no methods that take `self` and return
74// a changed copy (`fn x(self, value) -> Self` or `with_x`), only
75// conversions (`into_x`) and combinators that create something else
76// (like `SinkHandle::ignore_null`).
77// * Constructors are `new` and `with_x(...)` / `from_x(...)` associated
78// functions (like `ContainerShape::with_len`, `Context::with` or
79// `Error::with_offset`).
80// * Types that are configured in one expression or as constants (the
81// configurations of the formats and `Limits`) have a separate builder
82// type, `XBuilder`, created with `X::builder()` (or `x.into_builder()`).
83// Its methods have the names of the setters without `set_` and
84// `build()` returns the value.
85//
86// # Internal APIs
87//
88// The `#[doc(hidden)]` items (mostly methods named `__private_*`) are not
89// public API, even though other crates of deser use some of them.
90//
91// The rule: hidden methods may make things faster, they must not decide
92// how values are represented. Types implemented by hand cannot implement
93// them, so they would behave differently from derived types. What changes
94// the representation goes through public API that every type can
95// implement (like `Describe::unit_struct`, which decides if newtype
96// variants of internally tagged enums are the tag alone). Bytes are a
97// closed exception and raw values and collections are the known
98// violations to resolve (see below).
99//
100// Every hidden method is marked with the group it belongs to:
101//
102// * Internal fast paths exist for performance (or code size) only. A
103// type or sink that does not implement them behaves the same, just
104// slower: implementations must behave exactly like the default
105// implementation. Crates outside of deser-core may forward or override
106// them (deser-value, deser-validate and deser-serde do) but must never
107// depend on them for how values are deserialized or serialized. Whether
108// they become public API is not decided yet.
109// * The internal specialization of bytes lets `Vec<u8>`, `[u8; N]` and
110// friends be deserialized from and serialized as bytes. Only `u8` (and
111// adapters forwarding to it) implements it.
112// * Internal protocols change behavior: raw values (see `ext::Raw`) and
113// collections that collect the values of repeated keys. What formats
114// need is public (`State::declare_raw_format`, `State::take_raw_request`,
115// `Error::is_raw_request`,
116// `ContainerShape::with_multimap`, `DeserializeDriver::multimap_value`
117// and `de::missing_multimap_value`), the side
118// of the types (which types want raw values or collect, used by the
119// derive and the containers of deser-core) is not. These break the
120// rule above: types implemented by hand cannot be raw values or
121// collect. They have to become public API (or be replaced by public
122// API) before 1.0, new protocols must not be added.
123//
124// Everything the derive refers to is in `__derive` below.
125
126// Everything the code generated by the derive refers to. Not public API.
127// Standard library items are re-exported so that the generated code does
128// not depend on what the names refer to where the derive is used.
129#[cfg(feature = "derive")]
130#[doc(hidden)]
131pub mod __derive {
132 pub use alloc::borrow::Cow;
133 pub use alloc::boxed::Box;
134 pub use alloc::string::String;
135 pub use alloc::vec::Vec;
136 pub use core::convert::Into;
137 pub use core::default::Default;
138 pub use core::marker::{PhantomData, Send, Sync};
139 pub use core::mem::replace;
140 pub use core::option::Option::{self, None, Some};
141 pub use core::primitive::{str, u8};
142 pub use core::result::Result::{Err, Ok};
143 pub use core::unreachable;
144 pub type Result<T> = core::result::Result<T, super::Error>;
145 pub type StrCow<'a> = Cow<'a, str>;
146
147 pub use crate::adapters::{DerivedDeserialize, DerivedSerialize};
148 pub use crate::de::atoms::{
149 atom_into, atom_into_handle, borrowed_atom_into, borrowed_atom_into_handle, field_update,
150 unit_struct,
151 };
152 pub use crate::de::enums::{
153 AdjacentlyTaggedSink, ArenaVariant, EnumKey, ExternallyTaggedSink, IgnoredContent,
154 IgnoredVariant, InternallyTaggedSink, OtherVariant, Tag, UnitEnum, UntaggedTry,
155 ValueVariant, VariantMaker, VariantNames, Variants, atom_sink, unit_enum_atom_into,
156 unit_enum_sink, untagged_atom, untagged_borrowed_atom, untagged_fallback, untagged_handle,
157 };
158 pub use crate::de::fields::{
159 Collect, FieldKeySink, FieldSlot, FieldValue, NextField, StructFields, StructFinish,
160 StructInfo, StructSink, StructUpdateSink, UpdateFields, collected_errors, missing_field,
161 new_missing_field_error, no_field_slot,
162 };
163 pub use crate::de::mapped::mapped;
164 pub use crate::de::recording::RecordBuf;
165 pub use crate::de::unknown::{unclaimed_keys, unknown_field};
166 pub use crate::de::update::UpdateTarget;
167 pub use crate::error::unknown_variant;
168 pub use crate::ser::begin::{
169 Begin, FIELDS_END, IndexedSeq, IndexedSeqEmitter, IndexedStruct, PlainSink, StructField,
170 describe_struct, emit_plain_field, serialize_indexed,
171 };
172 pub use crate::ser::enums::{
173 EntrySer, FieldSer, FieldsSer, FlatFieldsSer, SeqSer, TaggedContent, TaggedNewtype,
174 UnitName, UnitVariants, begin_unit, describe_unit, serialize_unit, skipped_variant,
175 };
176 pub use crate::ser::flatten::FlattenedStruct;
177
178 #[cfg(feature = "open-enums")]
179 pub use crate::de::DeserializeArc;
180 #[cfg(feature = "open-enums")]
181 pub use crate::open_enum::{
182 OpenEnumInfo, OpenRepr, VariantEntry, VariantValue,
183 container_shape as open_enum_container_shape, describe as open_enum_describe,
184 deserialize_arc as open_enum_deserialize_arc, deserialize_box as open_enum_deserialize_box,
185 serialize as open_enum_serialize,
186 };
187 #[cfg(feature = "open-enums")]
188 pub use alloc::sync::Arc;
189}