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

bnb/guide/
mod.rs
