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