nimble_derive/
lib.rs

1#![forbid(unsafe_code)]
2#![deny(missing_docs, unstable_features)]
3//! # Nimble
4//!
5//! Async friendly, simple and fast binary encoding/decoding in Rust.
6//!
7//! ## Binary encoding scheme
8//!
9//! This crate uses a minimal binary encoding scheme. For example, consider the following `struct`:
10//!
11//! ```
12//! struct MyStruct {
13//!     a: u8,
14//!     b: u16,
15//! }
16//! ```
17//!
18//! `encode()` will serialize this into `Vec` of size `3` (which is the sum of sizes of `u8` and `u16`).
19//!
20//! Similarly, for types which can have dynamic size (`Vec`, `String`, etc.), `encode()` prepends the size of encoded value
21//! as `u64`.
22//!
23//! ## Usage
24//!
25//! Add `nimble` in your `Cargo.toml`'s `dependencies` section:
26//!
27//! ```toml
28//! [dependencies]
29//! nimble = { version = "0.2", features = ["derive"] }
30//! ```
31//!
32//! Or, if you are in an environment based on `tokio`, use:
33//!
34//! ```toml
35//! [dependencies]
36//! nimble = { version = "0.2", features = ["derive", "tokio"] }
37//! ```
38//!
39//! For encoding and decoding, any type must implement two traits provided by this crate, i.e., `Encode` and `Decode`. For
40//! convenience, `nimble` provides `derive` macros (only when `"derive"` feature is enabled) to implement these traits.
41//!
42//! ```rust,ignore
43//! use nimble::{Encode, Decode};
44//!
45//! #[derive(Encode, Decode)]
46//! struct MyStruct {
47//!     a: u8,
48//!     b: u16,
49//! }
50//! ```
51//!
52//! Now you can use `encode()` and `decode()` functions to encode and decode values of `MyStruct`. In addition to this, you
53//! can also use `MyStruct::encode_to()` function to encode values directly to a type implementing `AsyncWrite` and
54//! `MyStruct::decode_from()` function to decode values directly from a type implementing `AsyncRead`.
55//!
56//! > Note: Most of the functions exposed by this crate are `async` functions and returns `Future` values. So, you'll need
57//! an executor to drive the `Future` returned from these functions. `async-std` and `tokio` are two popular options.
58//!
59//! ### Features
60//!
61//! - `tokio`: Select this feature when you are using `tokio`'s executor to drive `Future` values returned by functions in
62//!   this crate. This implements `Encode` and `Decode` using `tokio`'s `AsyncRead`/`AsyncWrite` traits.
63//!   - **Disabled** by default.
64//! - `derive`: Enables derive macros for implementing `Encode` and `Decode` traits.
65//!   - **Disabled** by default.
66extern crate proc_macro;
67
68mod context;
69mod decode;
70mod encode;
71mod util;
72
73#[proc_macro_derive(Encode)]
74/// Derive macro to implement `Encode` trait
75pub fn derive_encode(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
76    encode::derive(input)
77}
78
79#[proc_macro_derive(Decode)]
80/// Derive macro to implement `Decode` trait
81pub fn derive_decode(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
82    decode::derive(input)
83}
nimble_derive/lib.rs

nimble_derive/
lib.rs
