postcard_schema/
lib.rs

1#![cfg_attr(not(any(test, feature = "use-std")), no_std)]
2#![warn(missing_docs)]
3#![cfg_attr(docsrs, feature(doc_cfg))]
4//! # Postcard Schema
5
6pub mod impls;
7pub mod key;
8pub mod schema;
9
10/// Derive [`Schema`] for a struct or enum
11///
12/// # Examples
13///
14/// ```
15/// use postcard_schema::Schema;
16///
17/// #[derive(Schema)]
18/// struct Point {
19///     x: i32,
20///     y: i32,
21/// }
22/// ```
23///
24/// # Attributes
25///
26/// ## `#[serde(rename = "name")]`
27///
28/// The names of fields, containers, and variants in derived schemas respect `#[serde(rename = "name")]`
29/// attributes. Note that this does not include variants like `#[serde(rename(serialize = "ser_name"))]`
30/// or `#[serde(rename_all = "...")]`.
31///
32/// ## `#[postcard(crate = ...)]`
33///
34/// The `#[postcard(crate = ...)]` attribute can be used to specify a path to the `postcard_schema`
35/// crate instance to use when referring to [`Schema`] and [schema types](schema) from generated
36/// code. This is normally only applicable when invoking re-exported derives from a different crate.
37///
38/// ```
39/// # use postcard_schema::Schema;
40/// use postcard_schema as reexported_postcard_schema;
41///
42/// #[derive(Schema)]
43/// #[postcard(crate = reexported_postcard_schema)]
44/// struct Point {
45///     x: i32,
46///     y: i32,
47/// }
48/// ```
49///
50/// ## `#[postcard(bound = ...)]`
51///
52/// The `#[postcard(bound = ...)]` attribute can be used to overwrite the default bounds when
53/// deriving [`Schema`]. The default bounds are `T: Schema` for each type parameter `T`.
54///
55/// ```
56/// # use postcard_schema::Schema;
57/// #[derive(Schema)]
58/// #[postcard(bound = "")]
59/// struct Foo<F: Bar, T: Schema>(F::Wrap<T>);
60///
61/// trait Bar {
62///     type Wrap<T: Schema>: Schema;
63/// }
64///
65/// struct NoSchema;
66/// impl Bar for NoSchema {
67///     type Wrap<T: Schema> = Option<T>;
68/// }
69///
70/// Foo::<NoSchema, u8>::SCHEMA;
71/// ```
72#[cfg(feature = "derive")]
73pub use postcard_derive::Schema;
74
75/// A trait that represents a compile time calculated schema
76pub trait Schema {
77    /// A recursive data structure that describes the schema of the given
78    /// type.
79    const SCHEMA: &'static schema::NamedType;
80}
81
82#[cfg(test)]
83mod tests {
84    use super::*;
85
86    #[test]
87    fn crate_path() {
88        #[allow(unused)]
89        #[derive(Schema)]
90        #[postcard(crate = crate)]
91        struct Point {
92            x: i32,
93            y: i32,
94        }
95
96        assert_eq!(
97            Point::SCHEMA,
98            &schema::NamedType {
99                name: "Point",
100                ty: &schema::DataModelType::Struct(&[
101                    &schema::NamedValue {
102                        name: "x",
103                        ty: i32::SCHEMA
104                    },
105                    &schema::NamedValue {
106                        name: "y",
107                        ty: i32::SCHEMA
108                    },
109                ])
110            }
111        );
112    }
113}
postcard_schema/lib.rs

postcard_schema/
lib.rs
