Skip to main content

olean_export/
blean.rs

1//! blean, the binary export format.
2//!
3//! [`MAGIC`], then every [`Record`] in order, postcard encoded, each expression record
4//! followed by its [`Info`], ending with [`Record::End`]. Strings decode without copying,
5//! so a memory-mapped file is read in place.
6
7use crate::{
8    error::{corrupt, Result},
9    info::{Info, Tracker},
10    record::{Counts, Record, Sink, Table},
11};
12use std::{io::Write, mem};
13
14/// File signature; the final byte is the format version.
15pub const MAGIC: [u8; 8] = *b"BLEAN\0\0\x01";
16
17/// Writes records as blean.
18#[derive(Debug)]
19pub struct Blean<W: Write> {
20    out: W,
21    buf: Vec<u8>,
22    info: Tracker,
23    started: bool,
24}
25
26impl<W: Write> Blean<W> {
27    pub fn new(out: W) -> Self {
28        Self {
29            out,
30            buf: Vec::new(),
31            info: Tracker::new(),
32            started: false,
33        }
34    }
35}
36
37impl<W: Write> Sink for Blean<W> {
38    type Output = W;
39
40    fn record(&mut self, _: Option<u32>, r: &Record<'_>) -> Result<()> {
41        if !self.started {
42            self.out.write_all(&MAGIC)?;
43            self.started = true;
44        }
45        let mut buf = postcard::to_extend(r, mem::take(&mut self.buf))?;
46        if let Some(info) = self.info.observe(r)? {
47            buf = postcard::to_extend(&info, buf)?;
48        }
49        self.out.write_all(&buf)?;
50        buf.clear();
51        self.buf = buf;
52        Ok(())
53    }
54
55    fn finish(mut self) -> Result<W> {
56        self.out.flush()?;
57        Ok(self.out)
58    }
59}
60
61/// Whether `bytes` starts like a blean file.
62#[must_use]
63pub fn sniff(bytes: &[u8]) -> bool {
64    bytes.starts_with(&MAGIC)
65}
66
67/// The table sizes a complete blean file declares in its last 12 bytes, for presizing
68/// before reading. [`entries`] checks them against the records.
69pub fn counts(bytes: &[u8]) -> Result<Counts> {
70    let tail = bytes
71        .len()
72        .checked_sub(12)
73        .filter(|_| sniff(bytes))
74        .map(|at| &bytes[at..])
75        .ok_or_else(|| corrupt("not a blean file"))?;
76    Ok(postcard::from_bytes(tail)?)
77}
78
79/// The records of a complete blean file with each expression's info.
80///
81/// Strings borrow from `bytes`. Fails on a missing signature, a truncated stream, bytes
82/// after the end, or end counts that disagree with the records before them.
83pub fn entries(bytes: &[u8]) -> Result<Entries<'_>> {
84    let rest = bytes
85        .strip_prefix(&MAGIC)
86        .ok_or_else(|| corrupt("not a blean file"))?;
87    Ok(Entries {
88        rest,
89        next: Counts::default(),
90        done: false,
91    })
92}
93
94/// Iterator returned by [`entries`].
95#[derive(Debug)]
96pub struct Entries<'b> {
97    rest: &'b [u8],
98    next: Counts,
99    done: bool,
100}
101
102impl<'b> Entries<'b> {
103    fn step(&mut self) -> Result<(Record<'b>, Option<Info>)> {
104        let (r, rest) = postcard::take_from_bytes::<Record<'b>>(self.rest)?;
105        self.rest = rest;
106        if let Record::End(counts) = r {
107            self.done = true;
108            if counts != self.next || !rest.is_empty() {
109                return Err(corrupt("blean: bad end record"));
110            }
111            return Ok((r, None));
112        }
113        self.next.assign(&r);
114        let info = if r.table() == Some(Table::Exprs) {
115            let (info, rest) = postcard::take_from_bytes::<Info>(self.rest)?;
116            self.rest = rest;
117            Some(info)
118        } else {
119            None
120        };
121        Ok((r, info))
122    }
123}
124
125impl<'b> Iterator for Entries<'b> {
126    type Item = Result<(Record<'b>, Option<Info>)>;
127
128    fn next(&mut self) -> Option<Self::Item> {
129        if self.done {
130            return None;
131        }
132        let r = self.step();
133        self.done |= r.is_err();
134        Some(r)
135    }
136}
137
138/// Replay a complete blean file into `sink`.
139pub fn read<S: Sink>(bytes: &[u8], mut sink: S) -> Result<S::Output> {
140    let mut next = Counts::default();
141    for e in entries(bytes)? {
142        let r = e?.0;
143        sink.record(next.assign(&r), &r)?;
144    }
145    sink.finish()
146}