mlt_core/dump/
model.rs

1//! Data model for the annotated binary dump (see [`crate::dump`]).
2
3use crate::wire::StreamMeta;
4
5/// Whether a region is tile metadata or an opaque data payload.
6#[derive(Debug, Clone, Copy, PartialEq, Eq)]
7pub enum RegionKind {
8    /// Framing, schema, or stream-header bytes, annotated byte- and bit-for-byte.
9    Meta,
10    /// A stream payload, rendered as raw hex plus best-effort decoded values.
11    DataBlob,
12}
13
14/// How a [`RegionKind::DataBlob`] payload is decoded for display.
15///
16/// Best-effort: on any decode error the renderer falls back to raw hex.
17#[derive(Debug, Clone, Copy, PartialEq, Eq)]
18pub enum DecodeHint {
19    /// Nullability bitmap (byte-RLE -> packed bits).
20    Presence,
21    /// Boolean data stream (byte-RLE -> bools).
22    Bool,
23    /// Signed 32-bit integers (`i8`/`i32` columns).
24    I32,
25    /// Unsigned 32-bit integers (`u8`/`u32` columns, offsets, lengths).
26    U32,
27    /// Signed 64-bit integers (`i64` columns).
28    I64,
29    /// ALP offsets, put back on their frame of reference.
30    #[cfg(feature = "unstable-v2")]
31    Alp(crate::decoder::Alp),
32    /// Unsigned 64-bit integers (`u64` columns, 64-bit ids).
33    U64,
34    /// 32-bit floats.
35    F32,
36    /// 64-bit floats.
37    F64,
38    /// Opaque bytes (string / dictionary / FSST payloads); shown as hex + UTF-8 preview.
39    Bytes,
40    /// A raw LSB0 bitfield, not a stream: `ceil(num_values/8)` packed bytes.
41    #[cfg(feature = "unstable-v2")]
42    PackedBits,
43}
44
45/// One sub-field of a bit-packed byte, e.g. a nibble of `stream_type`.
46#[derive(Debug, Clone)]
47pub struct BitField {
48    /// Inclusive high bit index (7..=0, MSB first).
49    pub hi: u8,
50    /// Inclusive low bit index.
51    pub lo: u8,
52    /// The extracted field value.
53    pub raw: u64,
54    /// Human-readable meaning, e.g. `"physical = VarInt"`.
55    pub meaning: String,
56}
57
58/// Stream metadata attached to a [`RegionKind::DataBlob`] so the renderer can decode it.
59#[derive(Debug, Clone, Copy)]
60pub struct BlobInfo {
61    pub meta: StreamMeta,
62    pub hint: DecodeHint,
63}
64
65/// A single annotated span of the tile buffer.
66///
67/// Emitted in pre-order. Containers bracket their children and may overlap them.
68/// Leaf regions partition the buffer exactly; the coverage test relies on this.
69#[derive(Debug, Clone)]
70pub struct Region {
71    /// Absolute byte offset into the tile buffer.
72    pub offset: usize,
73    pub len: usize,
74    /// Nesting depth, for indentation.
75    pub depth: usize,
76    /// Short label, e.g. `"column[2].type"` or `"num_values"`.
77    pub label: String,
78    /// Rendered scalar value (varint value, string, enum name), if any.
79    pub value: Option<String>,
80    /// Bit-level breakdown; empty unless this is a bit-packed byte.
81    pub bits: Vec<BitField>,
82    pub kind: RegionKind,
83    /// True for structural groups that span their children (excluded from coverage).
84    pub container: bool,
85    /// Present for `DataBlob` regions that carry decodable stream metadata.
86    pub blob: Option<BlobInfo>,
87}
88
89/// The full annotation of a tile: a flat, depth-tagged region list.
90pub struct DumpTree {
91    pub buf_len: usize,
92    /// Regions in pre-order (containers before their children).
93    pub regions: Vec<Region>,
94}
mlt_core/dump/model.rs

mlt_core/dump/
model.rs
