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//! - [`dispatch`] — `#[bin]` on an enum: tagged-union dispatch by wire `magic` or off-wire `tag`.
16//! - [`io`] — the `Source`/`Sink` I/O ladder.
17//! - [`errors`] — position-aware errors and the streaming `Incomplete` signal.
18//! - [`dual_use`] — compliant by default, deliberately violatable.
19//! - [`composition`] — how the pieces nest and size each other.
20//!
21//! # How the crate fits together
22//!
23//! One trait, [`Bits`](crate::Bits), is the keystone: a value that occupies a fixed
24//! number of bits. The arbitrary-width integers (`u1`..`u127`), `bool`, the primitive
25//! integers, and every type the macros generate all implement it, so they **compose
26//! as fields** without glue:
27//!
28//! - `#[bitfield]` packs several `Bits` values into one backing integer.
29//! - `#[derive(BitEnum)]` makes an enum a `Bits` value (an integer discriminant).
30//! - `#[bitflags]` makes a flag set a `Bits` value.
31//! - `#[bin]` reads/writes a whole message of `Bits` fields at arbitrary bit offsets,
32//! and a `#[bitfield]`/`BitEnum`/`#[bitflags]` drops in as one field.
33//! - `#[derive(BitsBuilder)]` adds a required-by-default builder to any of the above.
34//!
35//! Because the unit of composition is "a value of N bits", a 5-bit enum nests in a
36//! 16-bit bitfield which nests in a byte-aligned message — all checked at compile
37//! time by const-evaluated width arithmetic, never by the proc-macro guessing widths.
38
39pub mod bin_codec;
40pub mod bitfields;
41pub mod builders;
42pub mod composition;
43pub mod directives;
44pub mod dispatch;
45pub mod dual_use;
46pub mod enums;
47pub mod errors;
48pub mod flags;
49pub mod io;
50pub mod numbers;
51pub mod quick_start;