bnb/guide/
mod.rs

1//! The `bnb` guide — worked, runnable walkthroughs.
2//!
3//! Every page here is a normal rustdoc module whose examples are compiled and run as
4//! doctests, so nothing in the guide can drift from the code. Read the pages in the
5//! order listed in the [crate root](crate), or jump to a topic:
6//!
7//! - [`quick_start`] — a five-minute tour of every macro.
8//! - [`numbers`] — `u1`..`u127` and the [`Bits`](crate::Bits) trait.
9//! - [`bitfields`] — `#[bitfield]`: bit/byte order, widths, ranges, nesting.
10//! - [`enums`] — `#[derive(BitEnum)]`: catch-all, closed, `num_enum` parity.
11//! - [`flags`] — `#[bitflags]`: single-bit flag sets with set algebra.
12//! - [`builders`] — `#[derive(BitsBuilder)]`: the required-by-default builder.
13//! - [`bin_codec`] — `#[bin]`: a whole protocol header, end to end.
14//! - [`directives`] — the field-directive reference, one example each.
15//! - [`mapping`] — `#[bin(map/bw_map = …)]`: a whole struct mapped to/from a wire type.
16//! - [`dispatch`] — `#[bin]` on an enum: tagged-union dispatch by wire `magic` or off-wire `tag`.
17//! - [`io`] — the `Source`/`Sink` I/O ladder.
18//! - [`errors`] — position-aware errors and the streaming `Incomplete` signal.
19//! - [`dual_use`] — compliant by default, deliberately violatable.
20//! - [`composition`] — how the pieces nest and size each other.
21//!
22//! # How the crate fits together
23//!
24//! One trait, [`Bits`](crate::Bits), is the keystone: a value that occupies a fixed
25//! number of bits. The arbitrary-width integers (`u1`..`u127`), `bool`, the primitive
26//! integers, and every type the macros generate all implement it, so they **compose
27//! as fields** without glue:
28//!
29//! - `#[bitfield]` packs several `Bits` values into one backing integer.
30//! - `#[derive(BitEnum)]` makes an enum a `Bits` value (an integer discriminant).
31//! - `#[bitflags]` makes a flag set a `Bits` value.
32//! - `#[bin]` reads/writes a whole message of `Bits` fields at arbitrary bit offsets,
33//!   and a `#[bitfield]`/`BitEnum`/`#[bitflags]` drops in as one field.
34//! - `#[derive(BitsBuilder)]` adds a required-by-default builder to any of the above.
35//!
36//! Because the unit of composition is "a value of N bits", a 5-bit enum nests in a
37//! 16-bit bitfield which nests in a byte-aligned message — all checked at compile
38//! time by const-evaluated width arithmetic, never by the proc-macro guessing widths.
39
40pub mod bin_codec;
41pub mod bitfields;
42pub mod builders;
43pub mod composition;
44pub mod directives;
45pub mod dispatch;
46pub mod dual_use;
47pub mod enums;
48pub mod errors;
49pub mod flags;
50pub mod io;
51pub mod mapping;
52pub mod numbers;
53pub mod quick_start;
bnb/guide/mod.rs

bnb/guide/
mod.rs
