musli_core/de/
mod.rs

1//! Traits for generically dealing with a decoding framework.
2//!
3//! The central traits are [Decode] and [Decoder].
4//!
5//! A type implementing [Decode] can use an [Decoder] to decode an instance of
6//! itself. This also comes with a derive allowing you to derive high
7//! performance decoding associated with native Rust types.
8//!
9//! Note that using derives directly from `musli_core` requires you to use the
10//! `#[musli(crate = musli_core)]` attribute.
11//!
12//! # Examples
13//!
14//! ```
15//! use musli_core::Decode;
16//!
17//! #[derive(Decode)]
18//! #[musli(crate = musli_core)]
19//! pub struct Person<'a> {
20//!     name: &'a str,
21//!     age: u32,
22//! }
23//! ```
24
25/// Derive which automatically implements the [`Decode` trait].
26///
27/// See the [`derives` module] for detailed documentation.
28///
29/// [`derives` module]: <https://docs.rs/musli/latest/musli/_help/derives/index.html>
30/// [`Decode` trait]: <https://docs.rs/musli/latest/musli/trait.Decode.html>
31///
32/// # Examples
33///
34/// ```
35/// use musli_core::Decode;
36///
37/// #[derive(Decode)]
38/// #[musli(crate = musli_core)]
39/// struct MyType {
40///     data: [u8; 128],
41/// }
42/// ```
43#[doc(inline)]
44pub use musli_macros::Decode;
45
46/// This is an attribute macro that must be used when implementing a
47/// [`Decoder`].
48///
49/// It is required to use because a [`Decoder`] implementation might introduce
50/// new associated types in the future, and this is [not yet supported] on a
51/// language level in Rust. So this attribute macro polyfills any missing types
52/// automatically.
53///
54/// [not yet supported]: https://rust-lang.github.io/rfcs/2532-associated-type-defaults.html
55///
56/// Note that if the `Cx` or `Mode` associated types are not specified, they
57/// will be defaulted to any type parameters which starts with the uppercase `C`
58/// or `M` respectively.
59///
60/// Note that using derives directly from `musli_core` requires you to use the
61/// `#[musli_core::decoder(crate = musli_core)]` attribute.
62///
63/// # Examples
64///
65/// ```
66/// use std::fmt;
67/// use std::marker::PhantomData;
68///
69/// use musli_core::Context;
70/// use musli_core::de::{Decoder, Decode};
71///
72/// struct MyDecoder<C, M> {
73///     cx: C,
74///     _marker: PhantomData<M>,
75/// }
76///
77/// #[musli_core::decoder(crate = musli_core)]
78/// impl<'de, C, M> Decoder<'de> for MyDecoder<C, M>
79/// where
80///     C: Context,
81///     M: 'static,
82/// {
83///     #[inline]
84///     fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
85///         write!(f, "32-bit unsigned integers")
86///     }
87///
88///     #[inline]
89///     fn decode_u32(self) -> Result<u32, Self::Error> {
90///         Ok(42)
91///     }
92/// }
93/// ```
94#[doc(inline)]
95pub use musli_macros::decoder;
96
97/// This is an attribute macro that must be used when implementing a
98/// [`Visitor`].
99///
100/// It is required to use because a [`Visitor`] implementation might introduce
101/// new associated types in the future, and this is [not yet supported] on a
102/// language level in Rust. So this attribute macro polyfills any missing types
103/// automatically.
104///
105/// Note that using derives directly from `musli_core` requires you to use the
106/// `#[musli_core::visitor(crate = musli_core)]` attribute.
107///
108/// [not yet supported]: https://rust-lang.github.io/rfcs/2532-associated-type-defaults.html
109/// [`Visitor`]: crate::de::Visitor
110///
111/// # Examples
112///
113/// ```
114/// use std::fmt;
115///
116/// use musli_core::Context;
117/// use musli_core::de::Visitor;
118///
119/// struct AnyVisitor;
120///
121/// #[musli_core::de::visitor(crate = musli_core)]
122/// impl<'de, C> Visitor<'de, C> for AnyVisitor
123/// where
124///     C: Context,
125/// {
126///     type Ok = ();
127///
128///     #[inline]
129///     fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
130///         write!(
131///             f,
132///             "a value that can be decoded into dynamic container"
133///         )
134///     }
135/// }
136/// ```
137#[doc(inline)]
138pub use musli_macros::visitor;
139
140/// This is an attribute macro that must be used when implementing a
141/// [`UnsizedVisitor`].
142///
143/// It is required to use because a [`UnsizedVisitor`] implementation might
144/// introduce new associated types in the future, and this is [not yet
145/// supported] on a language level in Rust. So this attribute macro polyfills
146/// any missing types automatically.
147///
148/// Note that using derives directly from `musli_core` requires you to use the
149/// `#[musli_core::visitor(crate = musli_core)]` attribute.
150///
151/// [not yet supported]: https://rust-lang.github.io/rfcs/2532-associated-type-defaults.html
152/// [`UnsizedVisitor`]: crate::de::UnsizedVisitor
153///
154/// # Examples
155///
156/// ```
157/// use std::fmt;
158///
159/// use musli_core::Context;
160/// use musli_core::de::UnsizedVisitor;
161///
162/// struct Visitor;
163///
164/// #[musli_core::de::unsized_visitor(crate = musli_core)]
165/// impl<'de, C> UnsizedVisitor<'de, C, [u8]> for Visitor
166/// where
167///     C: Context,
168/// {
169///     type Ok = ();
170///
171///     #[inline]
172///     fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
173///         write!(
174///             f,
175///             "a reference of bytes"
176///         )
177///     }
178/// }
179/// ```
180#[doc(inline)]
181pub use musli_macros::unsized_visitor;
182
183#[doc(inline)]
184pub use self::__traits::*;
185
186mod as_decoder;
187mod decode;
188mod decode_bytes;
189mod decode_owned;
190mod decode_packed;
191mod decode_slice_builder;
192mod decode_trace;
193mod decode_unsized;
194mod decode_unsized_bytes;
195mod decoder;
196mod entries_decoder;
197mod entry_decoder;
198mod map_decoder;
199mod sequence_decoder;
200mod size_hint;
201mod skip;
202mod unsized_visitor;
203mod variant_decoder;
204mod visitor;
205
206#[doc(hidden)]
207pub mod __traits {
208    pub use super::as_decoder::AsDecoder;
209    pub use super::decode::Decode;
210    pub use super::decode_bytes::DecodeBytes;
211    pub use super::decode_owned::DecodeOwned;
212    pub use super::decode_packed::DecodePacked;
213    pub use super::decode_slice_builder::DecodeSliceBuilder;
214    pub use super::decode_trace::DecodeTrace;
215    pub use super::decode_unsized::DecodeUnsized;
216    pub use super::decode_unsized_bytes::DecodeUnsizedBytes;
217    pub use super::decoder::{Decoder, TryFastDecode};
218    pub use super::entries_decoder::EntriesDecoder;
219    pub use super::entry_decoder::EntryDecoder;
220    pub use super::map_decoder::MapDecoder;
221    pub use super::sequence_decoder::SequenceDecoder;
222    pub use super::size_hint::SizeHint;
223    pub use super::skip::Skip;
224    pub use super::unsized_visitor::UnsizedVisitor;
225    pub use super::variant_decoder::VariantDecoder;
226    pub use super::visitor::Visitor;
227}
228
229#[doc(hidden)]
230pub mod utils;
musli_core/de/mod.rs

musli_core/de/
mod.rs
