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