postcard-bindgen 0.7.1

A crate to generate bindings for the postcard binary format for other languages than Rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145

//! # Postcard Bindgen
//!
//! This crate allows automatically generating javascript bindings to
//! serialize javascript objects to postcard format and vice versa.
//!
//! # Example
//!
//! This example shows how to generate a `npm` package out of the rust
//! structures. A new folder with the package name will be created. A
//! javascript file and typescript typings as well as a package.json
//! will be placed in it.
//!
//! ```rust
//! # use postcard_bindgen::{PostcardBindings, generate_bindings, javascript::{build_package, GenerationSettings}, PackageInfo};
//! # use serde::Serialize;
//! # extern crate alloc;
//! #[derive(Serialize, PostcardBindings)]
//! struct A(u8);
//!
//! #[derive(Serialize, PostcardBindings)]
//! struct B {
//!     a: u8
//! }
//!
//! #[derive(Serialize, PostcardBindings)]
//! enum C {
//!     A,
//!     B(u8),
//!     C(A, B),
//!     D { a: &'static str, b: B },
//! }
//!
//! fn main() {
//!     build_package(
//!         std::env::current_dir().unwrap().as_path(),
//!         PackageInfo {
//!             name: "test-bindings".into(),
//!             version: "0.1.0".try_into().unwrap(),
//!         },
//!         GenerationSettings::enable_all(),
//!         generate_bindings!(A, B, C),
//!     )
//!     .unwrap();
//! }
//! ```
//!
//! ```text
//! // JavaScript
//! import { serialize } form "test-bindings"
//!
//! const c = {
//!     tag: "C",
//!     value: [
//!         123,
//!         {
//!             a: 234
//!         }
//!     ]
//! }
//!
//! const bytes = serialize("C", c)
//! ```

#![cfg_attr(not(feature = "generating"), no_std)]
#![cfg_attr(docsrs, feature(doc_cfg))]

#[cfg(feature = "generating")]
#[cfg_attr(docsrs, doc(cfg(feature = "generating")))]
mod package;

#[cfg(feature = "generating")]
#[cfg_attr(docsrs, doc(cfg(feature = "generating")))]
pub mod javascript {
    pub use super::package::npm_package::build_npm_package as build_package;
    pub use postcard_bindgen_core::code_gen::js::GenerationSettings;
}

#[cfg(feature = "generating")]
#[cfg_attr(docsrs, doc(cfg(feature = "generating")))]
pub mod python {
    pub use super::package::pip_module::build_pip_module as build_package;
    pub use postcard_bindgen_core::code_gen::python::GenerationSettings;
}

#[cfg(feature = "generating")]
#[cfg_attr(docsrs, doc(cfg(feature = "generating")))]
pub use package::{PackageInfo, Version, VersionFromStrError};

/// Macro to annotate structs or enums for which bindings should be generated.
///
/// For this macro to work, the [`serde::Serialize`] macro must be derived as well.
///
/// # Example
/// ```rust
/// # use serde::Serialize;
/// # use postcard_bindgen_derive::PostcardBindings;
/// #[derive(Serialize, PostcardBindings)]
/// struct Test {
///    a: u32
/// }
/// ```
pub use postcard_bindgen_derive::PostcardBindings;

#[cfg(feature = "generating")]
#[doc(hidden)]
pub mod __private {
    pub use postcard_bindgen_core::{
        path::Path,
        registry::*,
        type_info::{GenBinding, ObjectMeta, ValueType},
    };
}

/// Macro to generate javascript and typescript binding strings which
/// can be exported into files.
///
/// The supplied structures needs to implement the `trait` [`crate::__private::JsBindings`].
/// This `trait` is automatically implemented when deriving the
/// [`postcard_bindgen_derive::PostcardBindings`] on the types.
///
/// # Example
/// ```rust
/// # use serde::Serialize;
/// # use postcard_bindgen::{PostcardBindings, generate_bindings};
/// #[derive(Serialize, PostcardBindings)]
/// struct Test {
///     field: u8
/// }
///
/// let bindings = generate_bindings!(Test);
/// ```
#[cfg(feature = "generating")]
#[cfg_attr(docsrs, doc(cfg(feature = "generating")))]
#[macro_export]
macro_rules! generate_bindings {
    ($( $x:ty ),*) => {
        {
            let mut reg = postcard_bindgen::__private::BindingsRegistry::default();
            $(
                <$x as postcard_bindgen::__private::JsBindings>::create_bindings(&mut reg);
            )*
            reg.into_entries()
        }
    };
}