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::PresenceCoded(coding) => {
212            use crate::codecs::presence_coding::{Unmetered, read};
213            match read(data, meta.num_values, coding, &mut Unmetered) {
214                Ok((_, bits)) => fmt_bits(bits.len(), |i| bits[i]),
215                Err(e) => format!("<undecodable: {e}>"),
216            }
217        }
218        #[cfg(feature = "unstable-v2")]
219        DecodeHint::PackedBits => {
220            let n = meta.num_values.into_usize();
221            let available = data.len() * 8;
222            if available < n {
223                return format!("<undecodable: needs {n} bits, got {available}>");
224            }
225            fmt_bits(n, |i| data[i / 8] >> (i % 8) & 1 == 1)
226        }
227        DecodeHint::Bool => fmt_res(RawStream::new(meta, data).decode_bools(dec)),
228        DecodeHint::I32 => fmt_res(RawStream::new(meta, data).decode_ints::<i32>(dec)),
229        DecodeHint::U32 => fmt_res(RawStream::new(meta, data).decode_ints::<u32>(dec)),
230        DecodeHint::I64 => fmt_res(RawStream::new(meta, data).decode_ints::<i64>(dec)),
231        #[cfg(feature = "unstable-v2")]
232        DecodeHint::Alp(params) => {
233            fmt_res(RawStream::new(meta, data).decode_alp_codes(params, dec))
234        }
235        DecodeHint::U64 => fmt_res(RawStream::new(meta, data).decode_ints::<u64>(dec)),
236        DecodeHint::F32 => fmt_res(RawStream::new(meta, data).decode_floats::<f32>(dec)),
237        DecodeHint::F64 => fmt_res(RawStream::new(meta, data).decode_floats::<f64>(dec)),
238        DecodeHint::Bytes => match std::str::from_utf8(data) {
239            Ok(s) => format!("utf-8 {:?}", truncate_str(s, 200)),
240            Err(_) => format!("<{} binary bytes>", data.len()),
241        },
242    }
243}
244
245/// Render the first 96 of `n` presence bits as a `0`/`1` string.
246fn fmt_bits(n: usize, bit: impl Fn(usize) -> bool) -> String {
247    let shown: String = (0..n.min(96))
248        .map(|i| if bit(i) { '1' } else { '0' })
249        .collect();
250    let more = if n > 96 { "…" } else { "" };
251    format!("{n} present-bits: {shown}{more}")
252}
253
254fn fmt_res<T: std::fmt::Display>(res: crate::MltResult<Vec<T>>) -> String {
255    match res {
256        Ok(v) => fmt_list(&v),
257        Err(e) => format!("<undecodable: {e}>"),
258    }
259}
260
261fn fmt_list<T: std::fmt::Display>(v: &[T]) -> String {
262    const MAX: usize = 48;
263    let shown = v
264        .iter()
265        .take(MAX)
266        .map(ToString::to_string)
267        .collect::<Vec<_>>()
268        .join(", ");
269    if v.len() > MAX {
270        format!("[{shown}, … ] ({} total)", v.len())
271    } else {
272        format!("[{shown}]")
273    }
274}
275
276fn truncate_str(s: &str, max: usize) -> String {
277    if s.chars().count() <= max {
278        s.to_string()
279    } else {
280        let head: String = s.chars().take(max).collect();
281        format!("{head}…")
282    }
283}
284
285/// Emit one or more hexdump rows for `bytes` starting at `offset`.
286/// The `annotation` is printed on the first row only.
287fn emit_bytes(
288    w: &mut impl Write,
289    offset: usize,
290    bytes: &[u8],
291    opts: &RenderOpts,
292    left_len: usize,
293    annotation: &str,
294) -> io::Result<()> {
295    if bytes.is_empty() {
296        let left = format!("{offset:08x}");
297        return emit_row(w, &left, left_len, annotation);
298    }
299    for (row, chunk) in bytes.chunks(opts.width).enumerate() {
300        let row_off = offset + row * opts.width;
301        let hex = chunk
302            .iter()
303            .map(|b| format!("{b:02x}"))
304            .collect::<Vec<_>>()
305            .join(" ");
306        let ascii: String = chunk
307            .iter()
308            .map(|&b| {
309                if (0x20..=0x7e).contains(&b) {
310                    b as char
311                } else {
312                    '.'
313                }
314            })
315            .collect();
316        let hexw = opts.width * 3;
317        let left = format!("{row_off:08x}  {hex:<hexw$}  {ascii}");
318        emit_row(w, &left, left_len, if row == 0 { annotation } else { "" })?;
319    }
320    Ok(())
321}
322
323/// Emit one row without trailing whitespace when the annotation is empty.
324fn emit_row(w: &mut impl Write, left: &str, left_len: usize, annotation: &str) -> io::Result<()> {
325    if annotation.is_empty() {
326        writeln!(w, "{left:<left_len$} |")
327    } else {
328        writeln!(w, "{left:<left_len$} | {annotation}")
329    }
330}
331
332#[derive(Clone, Copy)]
333enum Paint {
334    Label,
335    Value,
336    Dim,
337}
338
339fn paint(s: &str, opts: &RenderOpts, kind: Paint) -> String {
340    if !opts.color {
341        return s.to_string();
342    }
343    let code = match kind {
344        Paint::Label => "1",  // bold
345        Paint::Value => "36", // cyan
346        Paint::Dim => "2",    // dim
347    };
348    format!("\x1b[{code}m{s}\x1b[0m")
349}
mlt_core/dump/render.rs

mlt_core/dump/
render.rs
