postcard_bindgen/
lib.rs

1//! # Postcard Bindgen
2//!
3//! This crate allows automatically generating javascript bindings to
4//! serialize javascript objects to postcard format and vice versa.
5//!
6//! # Example
7//!
8//! This example shows how to generate a `npm` package out of the rust
9//! structures. A new folder with the package name will be created. A
10//! javascript file and typescript typings as well as a package.json
11//! will be placed in it.
12//!
13//! ```rust
14//! # use postcard_bindgen::{PostcardBindings, generate_bindings, javascript::{build_package, GenerationSettings}, PackageInfo};
15//! # use serde::Serialize;
16//! # extern crate alloc;
17//! #[derive(Serialize, PostcardBindings)]
18//! struct A(u8);
19//!
20//! #[derive(Serialize, PostcardBindings)]
21//! struct B {
22//!     a: u8
23//! }
24//!
25//! #[derive(Serialize, PostcardBindings)]
26//! enum C {
27//!     A,
28//!     B(u8),
29//!     C(A, B),
30//!     D { a: &'static str, b: B },
31//! }
32//!
33//! fn main() {
34//!     build_package(
35//!         std::env::current_dir().unwrap().as_path(),
36//!         PackageInfo {
37//!             name: "test-bindings".into(),
38//!             version: "0.1.0".try_into().unwrap(),
39//!         },
40//!         GenerationSettings::enable_all(),
41//!         generate_bindings!(A, B, C),
42//!     )
43//!     .unwrap();
44//! }
45//! ```
46//!
47//! ```text
48//! // JavaScript
49//! import { serialize } form "test-bindings"
50//!
51//! const c = {
52//!     tag: "C",
53//!     value: [
54//!         123,
55//!         {
56//!             a: 234
57//!         }
58//!     ]
59//! }
60//!
61//! const bytes = serialize("C", c)
62//! ```
63
64#![cfg_attr(not(feature = "generating"), no_std)]
65#![cfg_attr(docsrs, feature(doc_cfg))]
66
67#[cfg(feature = "generating")]
68#[cfg_attr(docsrs, doc(cfg(feature = "generating")))]
69mod package;
70
71#[cfg(feature = "generating")]
72#[cfg_attr(docsrs, doc(cfg(feature = "generating")))]
73pub mod javascript {
74    pub use super::package::npm_package::build_npm_package as build_package;
75    pub use postcard_bindgen_core::code_gen::js::GenerationSettings;
76}
77
78#[cfg(feature = "generating")]
79#[cfg_attr(docsrs, doc(cfg(feature = "generating")))]
80pub mod python {
81    pub use super::package::pip_module::build_pip_module as build_package;
82    pub use postcard_bindgen_core::code_gen::python::GenerationSettings;
83}
84
85#[cfg(feature = "generating")]
86#[cfg_attr(docsrs, doc(cfg(feature = "generating")))]
87pub use package::{PackageInfo, Version, VersionFromStrError};
88
89/// Macro to annotate structs or enums for which bindings should be generated.
90///
91/// For this macro to work, the [`serde::Serialize`] macro must be derived as well.
92///
93/// # Example
94/// ```rust
95/// # use serde::Serialize;
96/// # use postcard_bindgen_derive::PostcardBindings;
97/// #[derive(Serialize, PostcardBindings)]
98/// struct Test {
99///    a: u32
100/// }
101/// ```
102pub use postcard_bindgen_derive::PostcardBindings;
103
104#[cfg(feature = "generating")]
105#[doc(hidden)]
106pub mod __private {
107    pub use postcard_bindgen_core::{
108        path::Path,
109        registry::*,
110        type_info::{GenBinding, ObjectMeta, ValueType},
111    };
112}
113
114/// Macro to generate javascript and typescript binding strings which
115/// can be exported into files.
116///
117/// The supplied structures needs to implement the `trait` [`crate::__private::JsBindings`].
118/// This `trait` is automatically implemented when deriving the
119/// [`postcard_bindgen_derive::PostcardBindings`] on the types.
120///
121/// # Example
122/// ```rust
123/// # use serde::Serialize;
124/// # use postcard_bindgen::{PostcardBindings, generate_bindings};
125/// #[derive(Serialize, PostcardBindings)]
126/// struct Test {
127///     field: u8
128/// }
129///
130/// let bindings = generate_bindings!(Test);
131/// ```
132#[cfg(feature = "generating")]
133#[cfg_attr(docsrs, doc(cfg(feature = "generating")))]
134#[macro_export]
135macro_rules! generate_bindings {
136    ($( $x:ty ),*) => {
137        {
138            let mut reg = postcard_bindgen::__private::BindingsRegistry::default();
139            $(
140                <$x as postcard_bindgen::__private::JsBindings>::create_bindings(&mut reg);
141            )*
142            reg.into_entries()
143        }
144    };
145}
postcard_bindgen/lib.rs

postcard_bindgen/
lib.rs
