mlt_core/dump/
render.rs

1//! Renders a [`DumpTree`] as an annotated hexdump.
2
3use std::io::{self, Write};
4
5#[cfg(feature = "unstable-v2")]
6use usize_cast::IntoUsize as _;
7
8use super::model::{BlobInfo, DecodeHint, DumpTree, Region, RegionKind};
9use crate::Decoder;
10use crate::decoder::RawStream;
11
12/// How data-payload blobs are shown.
13#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
14pub enum DataMode {
15    /// Raw hex plus best-effort decoded values (default).
16    #[default]
17    Both,
18    /// Raw hex only.
19    Blob,
20    /// Decoded values only.
21    Decoded,
22    /// A one-line summary, no payload bytes.
23    Hidden,
24}
25
26/// Rendering options for [`render`].
27#[derive(Debug, Clone, Copy)]
28pub struct RenderOpts {
29    /// Hex bytes per row.
30    pub width: usize,
31    /// Show the bit-level breakdown of packed bytes.
32    pub show_bits: bool,
33    /// Emit ANSI color escapes.
34    pub color: bool,
35    /// How to render data payloads.
36    pub data_mode: DataMode,
37    /// Truncate raw payload hex to this many bytes (`0` = unlimited).
38    pub max_blob: usize,
39}
40
41impl Default for RenderOpts {
42    fn default() -> Self {
43        Self {
44            width: 16,
45            show_bits: true,
46            color: false,
47            data_mode: DataMode::Both,
48            max_blob: 256,
49        }
50    }
51}
52
53/// Render `tree` as an annotated hexdump.
54/// `buf` must be the buffer that was passed to [`super::annotate_tile`].
55pub fn render(
56    tree: &DumpTree,
57    buf: &[u8],
58    opts: &RenderOpts,
59    w: &mut impl Write,
60) -> io::Result<()> {
61    if opts.width == 0 {
62        return Err(io::Error::new(
63            io::ErrorKind::InvalidInput,
64            "render width must be non-zero",
65        ));
66    }
67    let mut dec = Decoder::default();
68    let left_len = left_width(opts.width);
69    for region in &tree.regions {
70        render_region(w, buf, region, opts, left_len, &mut dec)?;
71    }
72    Ok(())
73}
74
75fn left_width(width: usize) -> usize {
76    // "{off:08x}  " + hex(width*3) + "  " + ascii(width)
77    8 + 2 + width * 3 + 2 + width
78}
79
80fn render_region(
81    w: &mut impl Write,
82    buf: &[u8],
83    region: &Region,
84    opts: &RenderOpts,
85    left_len: usize,
86    dec: &mut Decoder,
87) -> io::Result<()> {
88    let indent = "  ".repeat(region.depth);
89
90    if region.container {
91        let left = format!("{:08x}", region.offset);
92        let annot = format!(
93            "{indent}{} ({} B)",
94            paint(&region.label, opts, Paint::Label),
95            region.len
96        );
97        writeln!(w, "{left:<left_len$} | {annot}")?;
98        return Ok(());
99    }
100
101    let bytes = &buf[region.offset..region.offset + region.len];
102
103    match region.kind {
104        RegionKind::Meta => render_meta(w, region, bytes, opts, left_len, &indent),
105        RegionKind::DataBlob => render_blob(w, region, bytes, opts, left_len, &indent, dec),
106    }
107}
108
109fn render_meta(
110    w: &mut impl Write,
111    region: &Region,
112    bytes: &[u8],
113    opts: &RenderOpts,
114    left_len: usize,
115    indent: &str,
116) -> io::Result<()> {
117    let annot = match &region.value {
118        Some(v) => format!(
119            "{indent}{}: {}",
120            paint(&region.label, opts, Paint::Label),
121            paint(v, opts, Paint::Value)
122        ),
123        None => format!("{indent}{}", paint(&region.label, opts, Paint::Label)),
124    };
125    emit_bytes(w, region.offset, bytes, opts, left_len, &annot)?;
126
127    if opts.show_bits {
128        for bf in &region.bits {
129            let annot = format!("{indent}  └ {bf}");
130            writeln!(w, "{:<left_len$} | {}", "", paint(&annot, opts, Paint::Dim))?;
131        }
132    }
133    Ok(())
134}
135
136fn render_blob(
137    w: &mut impl Write,
138    region: &Region,
139    bytes: &[u8],
140    opts: &RenderOpts,
141    left_len: usize,
142    indent: &str,
143    dec: &mut Decoder,
144) -> io::Result<()> {
145    let summary = blob_summary(region, bytes);
146
147    if opts.data_mode == DataMode::Hidden {
148        let annot = format!("{indent}{}", paint(&summary, opts, Paint::Dim));
149        let left = format!("{:08x}", region.offset);
150        writeln!(w, "{left:<left_len$} | {annot}")?;
151        return Ok(());
152    }
153
154    // Raw hex (unless Decoded-only).
155    if matches!(opts.data_mode, DataMode::Both | DataMode::Blob) {
156        let annot = format!("{indent}{}", paint(&summary, opts, Paint::Dim));
157        let shown = if opts.max_blob == 0 || bytes.len() <= opts.max_blob {
158            bytes
159        } else {
160            &bytes[..opts.max_blob]
161        };
162        emit_bytes(w, region.offset, shown, opts, left_len, &annot)?;
163        if shown.len() < bytes.len() {
164            let note = format!(
165                "{indent}  ... {} more bytes omitted (--max-blob to change)",
166                bytes.len() - shown.len()
167            );
168            writeln!(w, "{:<left_len$} | {}", "", paint(&note, opts, Paint::Dim))?;
169        }
170    }
171
172    // Decoded values (unless Blob-only).
173    if matches!(opts.data_mode, DataMode::Both | DataMode::Decoded)
174        && let Some(info) = region.blob
175    {
176        let decoded = decode_blob(info, bytes, dec);
177        let annot = format!("{indent}  decoded: {}", paint(&decoded, opts, Paint::Value));
178        writeln!(w, "{:<left_len$} | {annot}", "")?;
179    }
180    Ok(())
181}
182
183/// One-line description of a data blob for its annotation column.
184fn blob_summary(region: &Region, bytes: &[u8]) -> String {
185    match region.blob {
186        Some(info) => format!(
187            "{} [{:?} {:?}/{:?}, {} values, {} B]",
188            region.label,
189            info.meta.stream_type,
190            info.meta.encoding.logical,
191            info.meta.encoding.physical,
192            info.meta.num_values,
193            bytes.len()
194        ),
195        None => format!("{} [{} B]", region.label, bytes.len()),
196    }
197}
198
199/// Best-effort decode of a stream payload for display.
200/// Never panics; decode errors are rendered inline.
201fn decode_blob(info: BlobInfo, data: &[u8], dec: &mut Decoder) -> String {
202    // Bound memory/time per blob; the decoded values are dropped immediately.
203    dec.reset_budget();
204    let meta = info.meta;
205    match info.hint {
206        DecodeHint::Presence => match RawStream::new(meta, data).decode_bitvec(dec) {
207            Ok(bits) => fmt_bits(bits.len(), |i| bits[i]),
208            Err(e) => format!("<undecodable: {e}>"),
209        },
210        #[cfg(feature = "unstable-v2")]
211        DecodeHint::PackedBits => {
212            let n = meta.num_values.into_usize();
213            let available = data.len() * 8;
214            if available < n {
215                return format!("<undecodable: needs {n} bits, got {available}>");
216            }
217            fmt_bits(n, |i| data[i / 8] >> (i % 8) & 1 == 1)
218        }
219        DecodeHint::Bool => fmt_res(RawStream::new(meta, data).decode_bools(dec)),
220        DecodeHint::I32 => fmt_res(RawStream::new(meta, data).decode_ints::<i32>(dec)),
221        DecodeHint::U32 => fmt_res(RawStream::new(meta, data).decode_ints::<u32>(dec)),
222        DecodeHint::I64 => fmt_res(RawStream::new(meta, data).decode_ints::<i64>(dec)),
223        #[cfg(feature = "unstable-v2")]
224        DecodeHint::Alp(params) => {
225            fmt_res(RawStream::new(meta, data).decode_alp_codes(params, dec))
226        }
227        DecodeHint::U64 => fmt_res(RawStream::new(meta, data).decode_ints::<u64>(dec)),
228        DecodeHint::F32 => fmt_res(RawStream::new(meta, data).decode_floats::<f32>(dec)),
229        DecodeHint::F64 => fmt_res(RawStream::new(meta, data).decode_floats::<f64>(dec)),
230        DecodeHint::Bytes => match std::str::from_utf8(data) {
231            Ok(s) => format!("utf-8 {:?}", truncate_str(s, 200)),
232            Err(_) => format!("<{} binary bytes>", data.len()),
233        },
234    }
235}
236
237/// Render the first 96 of `n` presence bits as a `0`/`1` string.
238fn fmt_bits(n: usize, bit: impl Fn(usize) -> bool) -> String {
239    let shown: String = (0..n.min(96))
240        .map(|i| if bit(i) { '1' } else { '0' })
241        .collect();
242    let more = if n > 96 { "…" } else { "" };
243    format!("{n} present-bits: {shown}{more}")
244}
245
246fn fmt_res<T: std::fmt::Display>(res: crate::MltResult<Vec<T>>) -> String {
247    match res {
248        Ok(v) => fmt_list(&v),
249        Err(e) => format!("<undecodable: {e}>"),
250    }
251}
252
253fn fmt_list<T: std::fmt::Display>(v: &[T]) -> String {
254    const MAX: usize = 48;
255    let shown = v
256        .iter()
257        .take(MAX)
258        .map(ToString::to_string)
259        .collect::<Vec<_>>()
260        .join(", ");
261    if v.len() > MAX {
262        format!("[{shown}, … ] ({} total)", v.len())
263    } else {
264        format!("[{shown}]")
265    }
266}
267
268fn truncate_str(s: &str, max: usize) -> String {
269    if s.chars().count() <= max {
270        s.to_string()
271    } else {
272        let head: String = s.chars().take(max).collect();
273        format!("{head}…")
274    }
275}
276
277/// Emit one or more hexdump rows for `bytes` starting at `offset`.
278/// The `annotation` is printed on the first row only.
279fn emit_bytes(
280    w: &mut impl Write,
281    offset: usize,
282    bytes: &[u8],
283    opts: &RenderOpts,
284    left_len: usize,
285    annotation: &str,
286) -> io::Result<()> {
287    if bytes.is_empty() {
288        let left = format!("{offset:08x}");
289        return emit_row(w, &left, left_len, annotation);
290    }
291    for (row, chunk) in bytes.chunks(opts.width).enumerate() {
292        let row_off = offset + row * opts.width;
293        let hex = chunk
294            .iter()
295            .map(|b| format!("{b:02x}"))
296            .collect::<Vec<_>>()
297            .join(" ");
298        let ascii: String = chunk
299            .iter()
300            .map(|&b| {
301                if (0x20..=0x7e).contains(&b) {
302                    b as char
303                } else {
304                    '.'
305                }
306            })
307            .collect();
308        let hexw = opts.width * 3;
309        let left = format!("{row_off:08x}  {hex:<hexw$}  {ascii}");
310        emit_row(w, &left, left_len, if row == 0 { annotation } else { "" })?;
311    }
312    Ok(())
313}
314
315/// Emit one row without trailing whitespace when the annotation is empty.
316fn emit_row(w: &mut impl Write, left: &str, left_len: usize, annotation: &str) -> io::Result<()> {
317    if annotation.is_empty() {
318        writeln!(w, "{left:<left_len$} |")
319    } else {
320        writeln!(w, "{left:<left_len$} | {annotation}")
321    }
322}
323
324#[derive(Clone, Copy)]
325enum Paint {
326    Label,
327    Value,
328    Dim,
329}
330
331fn paint(s: &str, opts: &RenderOpts, kind: Paint) -> String {
332    if !opts.color {
333        return s.to_string();
334    }
335    let code = match kind {
336        Paint::Label => "1",  // bold
337        Paint::Value => "36", // cyan
338        Paint::Dim => "2",    // dim
339    };
340    format!("\x1b[{code}m{s}\x1b[0m")
341}
mlt_core/dump/render.rs

mlt_core/dump/
render.rs
