vest_lib/combinators/
mod.rs

1//! Combinators for composing binary data formats.
2//!
3//! Each format implements only the specification, proof, and executable traits
4//! that its semantics justify. In particular, deliberately malleable formats
5//! such as [`Alt`] and the permutation combinators do not claim
6//! [`NonMalleable`](crate::core::proof::NonMalleable). See the
7//! [combinator guide](https://secure-foundations.github.io/vest/guide/library/combinators.html)
8//! for the overall construction model.
9//!
10//! # Primitive combinators
11//!
12//! | Combinator | Description |
13//! |---|---|
14//! | [`Fixed<N>`] | Exactly `N` bytes |
15//! | [`Varied<Len>`] | Variable-length bytes determined by a length parameter |
16//! | [`U8`] | Unsigned 8-bit integer |
17//! | [`I8`] | Signed 8-bit integer |
18//! | [`U16Le`] / [`U16Be`] | Unsigned 16-bit integer (little/big-endian) |
19//! | [`I16Le`] / [`I16Be`] | Signed 16-bit integer (little/big-endian) |
20//! | [`U24Le`] / [`U24Be`] | Unsigned 24-bit integer represented as `u32` (little/big-endian) |
21//! | [`U32Le`] / [`U32Be`] | Unsigned 32-bit integer (little/big-endian) |
22//! | [`I32Le`] / [`I32Be`] | Signed 32-bit integer (little/big-endian) |
23//! | [`U64Le`] / [`U64Be`] | Unsigned 64-bit integer (little/big-endian) |
24//! | [`I64Le`] / [`I64Be`] | Signed 64-bit integer (little/big-endian) |
25//!
26//! # Higher-order combinators
27//!
28//! | Combinator | Description |
29//! |---|---|
30//! | [`Pair<A, B>`] | Sequential composition |
31//! | [`Choice<A, B>`] | Non-malleable ordered alternative |
32//! | [`Alt<A, B>`] | Malleable ordered alternative |
33//! | [`Opt<A>`] | Optional value |
34//! | [`Optional<A, B>`] | Same as `Pair(Opt<A>, B)`, but disambiguates `A` and `B` |
35//! | [`Star<A>`] | The Kleene star: zero-or-more repetitions |
36//! | [`Repeat<A, B>`] | Same as `Pair(Star<A>, B)`, but disambiguates `A` and `B` |
37//! | [`RepeatN<C, Len>`] | Fixed number of repetitions determined by a length parameter |
38//! | [`Array<N, C>`] | Array of values of length `N` |
39//! | [`Preceded<A, AVal, B>`] | Same as `Pair(A, B)`, but discards A's value and uses `a_val` as its serialization witness |
40//! | [`Terminated<A, B, BVal>`] | Same as `Pair(A, B)`, but discards B's value and uses `b_val` as its serialization witness |
41//! | [`Permute2<P1, P2>`] | Accepts either order of two components, serializes the declared order (malleable) |
42//! | [`Permute3<A, B, C>`] | Accepts any of the 6 orders of three components (malleable) |
43//! | [`Permute4<A, B, C, D>`] | Accepts any of the 24 orders of four components (malleable) |
44//! | [`Permute5<A, B, C, D, E>`] | Accepts any of the 120 orders of five components (malleable) |
45//! | [`Mapped<Inner, M>`] | Isomorphic format transformation via a [bijection](mapped::spec::SpecMapper) |
46//! | [`TryMap<Inner, M>`] | `Mapped` plus a parse-time `wf_in` check |
47//! | [`Refined<Inner, Pred>`] | Format refinement via a [predicate](crate::core::spec::SpecPred) |
48//! | [`Const<Inner, T>`] | Matches and returns a specific constant value |
49//! | [`PrefixTagged<Tg, T, Of>`] | A format preceded by a tag value |
50//! | [`SuffixTagged<Of, Tg, T>`] | A format followed by a tag value |
51//! | [`Cond<Inner>`] | Boolean-gated combinator (most often used in branches of `Choice` / `Alt`) |
52//! | [`Named<Inner>`] | Like `Inner`, but annotates runtime parse errors with a static format name |
53//!
54//! # Dependent combinators
55//!
56//! | Combinator | Description |
57//! |---|---|
58//! | [`Bind<A, B>`] | Like `Pair<A, B>`, but `B` can depend on `A`'s value |
59//!
60//! # Tail combinators
61//!
62//! | Combinator | Description |
63//! |---|---|
64//! | [`Tail`] | Like [`Varied`], but at the tail position (underspecify the format and allow trailing data) |
65//! | [`Eof`] | Signals end-of-file (no trailing data) |
66//! | [`OptionalEnd<C>`] | Same as `Optional<C, Eof>` (for convenience) |
67//! | [`RepeatTillEnd<C>`] | Same as `Repeat<C, Eof>` (for convenience) |
68//!
69//! # Marker combinators
70//!
71//! | Combinator | Description |
72//! |---|---|
73//! | [`Empty`] | Unit (nothing interesting, but still occupies zero bytes) |
74//! | [`Void`] | Bottom (no value can satisfy this format) |
75//!
76//! # Recursive combinators
77//!
78//! | Combinator | Description |
79//! |---|---|
80//! | [`FixWith<LIMIT, Body, Param>`] | Bounded fixpoint for recursive formats; use `Param = ()` for context-free recursion |
81pub mod bits;
82pub mod bytes;
83pub mod choice;
84pub mod cond;
85pub mod congruence;
86pub mod disjoint;
87pub mod implicit;
88pub mod length;
89pub mod mapped;
90pub mod marker;
91pub mod named;
92pub mod opt;
93pub mod permute;
94pub mod preceded;
95pub mod recursive;
96pub mod reference;
97pub mod refined;
98pub mod sints;
99pub mod star;
100pub mod tail;
101pub mod terminated;
102pub mod tuple;
103pub mod uints;
104
105pub use bits::Bits;
106pub use bytes::{AndThen, ExactLen, Fixed, Varied};
107pub use choice::{Alt, Choice, Dispatch, Sum};
108pub use cond::Cond;
109pub use implicit::Implicit;
110// Not part of the documented public API. These are still reachable because the `vest_dev`
111// experiments depend on them; they are hidden so they do not appear in the published catalog.
112#[doc(hidden)]
113pub use implicit::{DepCombinator, KVFormat, TLVal, TVLeaf, TVOr, VoidTag};
114pub use length::AsLen;
115pub use mapped::{Mapped, TryMap};
116pub use marker::{exec::ExecNever, Empty, Void};
117pub use named::Named;
118pub use opt::{Opt, Optional};
119pub use permute::{Permute2, Permute3, Permute4, Permute5};
120pub use preceded::Preceded;
121pub use recursive::FixWith;
122pub use reference::Ref;
123pub use refined::{Const, PrefixTagged, Refined, SuffixTagged};
124pub use sints::{I16Be, I16Le, I32Be, I32Le, I64Be, I64Le, I8};
125pub use star::{Array, Repeat, RepeatN, Star};
126pub use tail::{Eof, OptionalEnd, RepeatTillEnd, Tail};
127pub use terminated::Terminated;
128pub use tuple::{Bind, Pair};
129pub use uints::{U16Be, U16Le, U24Be, U24Le, U32Be, U32Le, U64Be, U64Le, U8};
vest_lib/combinators/mod.rs

vest_lib/combinators/
mod.rs
