retex_engine/

figures.rs

//! The figure cache (`docs/design/figure-cache.md`): a `tikzpicture` read
//! from a file is recorded (its key, the nodes it appends, its global
//! assignments, the control sequences and fonts it makes) and, when the
//! same picture starts again from the same state, replayed instead of
//! typeset. The records are kept in the process and, with a directory,
//! in files (`figfile.rs`), for the next builds: the key covers all
//! meanings, so it repeats from build to build (an edit elsewhere) rather
//! than from pass to pass (each pass reads new cross-references).
//!
//! `RETEX_FIGURES=stats` prints statistics at the end of each pass, `on`
//! replays, and `verify` typesets every picture and compares it with the
//! cache, reporting mismatches.

use std::collections::HashMap;
use std::rc::Rc;
use std::time::Instant;

use crate::Engine;
use crate::eqtb::{Loc, Val};
use crate::figfile::Record;
use crate::fingerprint::Fp;
use crate::hash::{CsId, CsKind};
use crate::input::{Level, LineSource};
use crate::maincontrol::Mode;
use crate::nodes::NodeRef;

/// What the cache does.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum FigureMode {
    /// Nothing.
    #[default]
    Off,
    /// Records statistics only.
    Stats,
    /// Records and replays.
    On,
    /// Records, and compares each picture with the cache.
    Verify,
}

/// The cache's state.
#[derive(Default)]
pub struct Figures {
    /// What it does.
    pub mode: FigureMode,
    /// `\tikzpicture` (the macro `\begin{tikzpicture}` calls), when on.
    pub cs: Option<CsId>,
    /// `\endtikzpicture`.
    pub end_cs: Option<CsId>,
    /// Where the records are kept between builds.
    pub dir: Option<std::path::PathBuf>,
    /// Whether the statistics are printed at the end of the run
    /// (`RETEX_FIGURES` given).
    pub report: bool,
    /// The picture being recorded.
    active: Option<Recording>,
    /// The picture being replayed: its group level and key.
    replaying: Option<(u16, u64)>,
    /// The pictures recorded.
    pub pictures: Vec<Picture>,
    /// Recorded pictures by key.
    cache: HashMap<u64, Record>,
    /// Pictures replayed, and the time their recording took.
    hits: (usize, u64),
    /// Mismatches found by `verify`.
    pub mismatches: Vec<String>,
    /// The names of the control sequences hashed so far, and their hash
    /// (names are only ever added).
    names: (usize, u64),
}

/// A picture being recorded.
struct Recording {
    /// The group level of its environment: it ends when the group does.
    level: u16,
    started: Instant,
    file: String,
    line: i32,
    /// The hash of its source text, if read from a file.
    source: Option<u64>,
    /// Its key (`on` and `verify`).
    key: Option<u64>,
    globals: Vec<Loc>,
    reasons: Vec<&'static str>,
    /// The semantic nest's depth, its current list and that list's tail
    /// when the picture began.
    nest: usize,
    head: NodeRef,
    tail: NodeRef,
    /// Whether it began in vertical mode (its `\leavevmode` starts a
    /// paragraph).
    vertical: bool,
    hash_len: usize,
    fonts_len: usize,
    /// The fonts' identifiers when it began.
    id_cs: Vec<CsId>,
    diagnostics_len: usize,
}

/// A picture recorded, for the statistics.
pub struct Picture {
    /// The file of its `\begin{tikzpicture}`.
    pub file: String,
    /// The line of its `\begin{tikzpicture}`.
    pub line: i32,
    /// Microseconds from its start to the end of its group.
    pub us: u64,
    /// The hash of its source text, if read from a file.
    pub source: Option<u64>,
    /// The number of global assignments it made.
    pub globals: usize,
    /// Why it could not be cached (empty: it could).
    pub reasons: Vec<&'static str>,
}

impl Figures {
    /// Whether a picture is being recorded.
    #[inline]
    pub fn recording(&self) -> bool {
        self.active.is_some()
    }

    /// Whether a picture is being recorded or replayed.
    #[inline]
    pub fn busy(&self) -> bool {
        self.active.is_some() || self.replaying.is_some()
    }

    /// Notes something that stops the picture being recorded from being
    /// cached.
    #[inline]
    pub fn taint(&mut self, why: &'static str) {
        if let Some(r) = &mut self.active
            && !r.reasons.contains(&why)
        {
            r.reasons.push(why);
        }
    }

    /// Notes a global assignment.
    #[inline]
    pub fn global(&mut self, loc: Loc) {
        if let Some(r) = &mut self.active {
            r.globals.push(loc);
        }
    }

    /// The statistics, as lines for the terminal.
    pub fn summary(&self) -> String {
        let n = self.pictures.len();
        let ok: Vec<&Picture> = self
            .pictures
            .iter()
            .filter(|p| p.reasons.is_empty())
            .collect();
        let total: u64 = self.pictures.iter().map(|p| p.us).sum();
        let cached: u64 = ok.iter().map(|p| p.us).sum();
        let mut out = format!(
            "[figures] {n} pictures typeset, {:.3} s; {} cacheable, {:.3} s; {} replayed, {:.3} s saved\n",
            total as f64 / 1e6,
            ok.len(),
            cached as f64 / 1e6,
            self.hits.0,
            self.hits.1 as f64 / 1e6,
        );
        let mut reasons: Vec<(&str, usize)> = Vec::new();
        for p in &self.pictures {
            for r in &p.reasons {
                match reasons.iter_mut().find(|(k, _)| k == r) {
                    Some((_, c)) => *c += 1,
                    None => reasons.push((r, 1)),
                }
            }
        }
        reasons.sort_by(|a, b| b.1.cmp(&a.1));
        for (r, c) in reasons {
            out.push_str(&format!("[figures]   {c} {r}\n"));
        }
        for m in &self.mismatches {
            out.push_str(&format!("[figures] mismatch: {m}\n"));
        }
        out
    }
}

/// Where the `\end{tikzpicture}` matching the picture just begun starts in
/// `text` (comments skipped, nested pictures counted).
fn end_offset(text: &[u8]) -> Option<usize> {
    let (begin, end): (&[u8], &[u8]) = (b"\\begin{tikzpicture}", b"\\end{tikzpicture}");
    let mut depth = 1;
    let mut i = 0;
    while i < text.len() {
        match text[i] {
            b'\\' if text[i..].starts_with(end) => {
                depth -= 1;
                if depth == 0 {
                    return Some(i);
                }
                i += end.len();
            }
            b'\\' if text[i..].starts_with(begin) => {
                depth += 1;
                i += begin.len();
            }
            // A control symbol: `\%` is no comment.
            b'\\' => i += 2,
            b'%' => {
                while i < text.len() && text[i] != b'\n' {
                    i += 1;
                }
            }
            _ => i += 1,
        }
    }
    None
}

/// The characters of `buf` from `loc`, as UTF-8.
fn line_rest(buf: &[u32], loc: usize) -> Vec<u8> {
    let s: String = buf[loc.min(buf.len())..]
        .iter()
        .filter_map(|&c| char::from_u32(c))
        .collect();
    s.into_bytes()
}

/// The text after position `loc` of the line `buf` and the rest of the
/// file `data` from `pos` (the two joined by a line end), up to the end of
/// the matching `\end{tikzpicture}`; `None` without one.
fn picture_source(buf: &[u32], loc: usize, data: &[u8], pos: usize) -> Option<Vec<u8>> {
    let mut text = line_rest(buf, loc);
    text.push(b'\n');
    text.extend_from_slice(&data[pos.min(data.len())..]);
    let i = end_offset(&text)?;
    text.truncate(i + b"\\end{tikzpicture}".len());
    Some(text)
}

/// Lua functions (`\luafunction`, `\luadef`) whose results depend on
/// their arguments only: expl3's.
const PURE_LUA_FUNCTIONS: &[&[u8]] = &[b"__str_if_eq:nn", b"__kernel_str_mdfive_hash:n"];

impl Engine {
    /// Before callback `name` runs: while recording, notes Lua code of a
    /// package's own.
    #[inline]
    pub(crate) fn figure_callback(&mut self, name: &str) {
        if self.figures.recording()
            && let Some(h) = self.lua.clone()
            && h.foreign_callback(name)
        {
            self.figures.taint("Lua callbacks");
        }
    }

    /// Before Lua function `cs` runs: while recording, notes it unless it
    /// is pure.
    #[inline]
    pub(crate) fn figure_lua_function(&mut self) {
        if self.figures.recording() && !PURE_LUA_FUNCTIONS.contains(&self.hash.name(self.cur_cs)) {
            self.figures.taint("Lua code");
        }
    }

    /// Whether `\write` stream `stream` goes to a file.
    pub(crate) fn write_file_open(&self, stream: i32) -> bool {
        (0..=127).contains(&stream) && self.printer.write_open(stream as u32)
    }

    /// At a macro call: starts recording or replaying a picture at
    /// `\tikzpicture`. Returns whether the macro is not to be expanded (a
    /// replayed picture's `\tikzpicture` and `\endtikzpicture`).
    #[inline]
    pub(crate) fn check_figure(&mut self) -> bool {
        if self.figures.cs.is_none() {
            return false;
        }
        if let Some((level, _)) = self.figures.replaying {
            return self.figures.end_cs == Some(self.cur_cs) && self.save.cur_level == level;
        }
        if self.figures.cs == Some(self.cur_cs) && !self.figures.recording() {
            return self.start_figure();
        }
        false
    }

    /// The index of the innermost input file's level.
    fn file_level(&self) -> Option<usize> {
        self.input
            .stack
            .iter()
            .rposition(|l| matches!(l, Level::Text(t) if t.is_input_file))
    }

    /// The key of the picture whose source hashes to `source`, read from
    /// the input with SyncTeX tag `tag`: the state it starts from
    /// (meanings, registers, fonts, mode, SyncTeX).
    fn figure_key(&mut self, source: u64, tag: u32) -> u64 {
        let meanings = self.figure_meanings();
        let mut fp = Fp::default();
        fp.u(source);
        fp.u(meanings);
        fp.u(self.fp_registers());
        fp.u(self.fonts.fonts.len() as u64);
        for f in &self.fonts.fonts {
            fp.bytes(&f.name);
            fp.i(f.size.into());
        }
        fp.u(matches!(self.mode, Mode::Vertical | Mode::InternalVertical).into());
        fp.u(self.nodes.sync.is_some().into());
        fp.u(tag.into());
        fp.get()
    }

    /// The hash of the meanings, as [`Engine::fp_meanings`] (which `--watch`
    /// uses) but faster: the names hashed once, the macros' tokens once
    /// per macro.
    fn figure_meanings(&mut self) -> u64 {
        if self.fp_cache.is_none() {
            self.prepare_fingerprints();
        }
        let (done, h) = self.figures.names;
        let mut names = if done == 0 {
            Fp::default()
        } else {
            Fp::resume(h)
        };
        for i in done..self.hash.len() {
            let cs = CsId(i as u32);
            names.bytes(self.hash.name(cs));
            names.debug(self.hash.kind(cs));
        }
        self.figures.names = (self.hash.len(), names.get());
        let mut h = Fp::default();
        h.u(names.get());
        for s in &self.eqtb.cs {
            h.u(s.level.into());
            self.fp_meaning(&mut h, &s.val);
        }
        h.get()
    }

    /// The file of the record with key `key`.
    fn figure_path(&self, key: u64) -> Option<std::path::PathBuf> {
        Some(self.figures.dir.as_ref()?.join(format!("{key:016x}.fig")))
    }

    /// Loads the record with key `key` from its file into the cache, if
    /// there is one; SyncTeX lines of the input with tag `tag` move to
    /// `line`.
    fn load_figure(&mut self, key: u64, tag: u32, line: i32) {
        let Some(path) = self.figure_path(key) else {
            return;
        };
        let Ok(data) = std::fs::read(&path) else {
            return;
        };
        match self.figure_from_bytes(&data, key, tag, line) {
            Ok(rec) => {
                self.figures.cache.insert(key, rec);
                // Used now: the cache is trimmed by age.
                if let Ok(f) = std::fs::File::options().write(true).open(&path) {
                    let _ = f.set_modified(std::time::SystemTime::now());
                }
            }
            Err(_) => {
                let _ = std::fs::remove_file(&path);
            }
        }
    }

    /// Writes record `rec` with key `key` to its file; `Err`: why it
    /// cannot be.
    fn save_figure(&self, key: u64, rec: &Record) -> Result<(), &'static str> {
        let Some(path) = self.figure_path(key) else {
            return Ok(());
        };
        let bytes = self.figure_bytes(key, rec)?;
        if let Some(dir) = path.parent() {
            let _ = std::fs::create_dir_all(dir);
        }
        // Whole or not at all: another build may read it.
        let tmp = path.with_extension(format!("tmp{}", retex_kpath::process_id()));
        if std::fs::write(&tmp, bytes).is_ok() {
            let _ = std::fs::rename(&tmp, &path);
        }
        Ok(())
    }

    fn start_figure(&mut self) -> bool {
        // The picture's source: the file being read, right after
        // `\begin{tikzpicture}`.
        let mut source = None;
        let mut file = String::new();
        let mut line = 0;
        let mut tag = 0;
        if let Some(i) = self.file_level()
            && let Level::Text(t) = &self.input.stack[i]
        {
            file = String::from_utf8_lossy(&t.name).into_owned();
            line = t.line;
            tag = t.sync.0;
            let before: String = t.buf[..t.loc.min(t.buf.len())]
                .iter()
                .filter_map(|&c| char::from_u32(c))
                .collect();
            if before.trim_end().ends_with("\\begin{tikzpicture}")
                && let LineSource::File { data, pos } = &t.source
                && let Some(text) = picture_source(&t.buf, t.loc, data, *pos)
            {
                let mut fp = Fp::default();
                fp.bytes(&text);
                source = Some(fp.get());
            }
        }
        // A picture an earlier build could not cache is not keyed again
        // (the key takes milliseconds).
        let known_uncacheable = source.is_some_and(|s| {
            self.figures
                .dir
                .as_ref()
                .is_some_and(|d| d.join(format!("{s:016x}.no")).exists())
        });
        let key = match (self.figures.mode, source) {
            (FigureMode::On | FigureMode::Verify, Some(s)) if !known_uncacheable => {
                Some(self.figure_key(s, tag))
            }
            _ => None,
        };
        if let Some(k) = key
            && !self.figures.cache.contains_key(&k)
        {
            self.load_figure(k, tag, line);
        }
        if self.figures.mode == FigureMode::On
            && let Some(k) = key
            && self.figures.cache.contains_key(&k)
            && self.replay_figure(k)
        {
            if std::env::var_os("RETEX_FIGURES_DEBUG").is_some() {
                eprintln!("[figures] replayed {file}:{line} ({k:016x})");
            }
            return true;
        }
        let mut reasons = Vec::new();
        if source.is_none() {
            reasons.push("not read from a file");
        }
        let cl = self.cur_list();
        self.figures.active = Some(Recording {
            level: self.save.cur_level,
            started: Instant::now(),
            file,
            line,
            source,
            key,
            globals: Vec::new(),
            reasons,
            nest: self.nest.len(),
            head: cl.head,
            tail: cl.tail,
            vertical: matches!(self.mode, Mode::Vertical | Mode::InternalVertical),
            hash_len: self.hash.len(),
            fonts_len: self.fonts.fonts.len(),
            id_cs: self.fonts.id_cs.clone(),
            diagnostics_len: self.diagnostics.as_ref().map_or(0, Vec::len),
        });
        false
    }

    /// While recording, a paragraph with something in it ends: if it is the
    /// one the picture is in, or one it started, its lines go to the list
    /// around it, which a record does not hold (an empty one adds nothing:
    /// LaTeX's paragraph hooks end the paragraph just started and start it
    /// again).
    pub(crate) fn figure_paragraph_end(&mut self) {
        let nest = self.nest.len();
        // `\par` elsewhere than in a paragraph ends nothing.
        if self.mode != Mode::Horizontal {
            return;
        }
        if let Some(r) = &self.figures.active
            && (nest == r.nest || (r.vertical && nest == r.nest + 1))
        {
            self.figures.taint("ends a paragraph");
        }
    }

    /// Starts replaying the picture with key `key`: its control sequences
    /// and fonts are made and its source is skipped up to its
    /// `\end{tikzpicture}`. Returns `false` (and changes nothing that
    /// matters) if it cannot be.
    fn replay_figure(&mut self, key: u64) -> bool {
        let Some(level_index) = self.file_level() else {
            return false;
        };
        let entry = &self.figures.cache[&key];
        let names = entry.names.clone();
        let fonts = entry.fonts.clone();
        let font_ids = entry.font_ids.clone();
        // The fonts first: they must get the ids they had.
        let first = self.fonts.fonts.len();
        for (k, (name, size)) in fonts.iter().enumerate() {
            let got = self.load_font(name, *size);
            if got != Some((first + k) as u32) {
                if std::env::var_os("RETEX_FIGURES_DEBUG").is_some() {
                    eprintln!(
                        "[figures] replay refused: font {} at {size} got {got:?}, not {}",
                        String::from_utf8_lossy(name),
                        first + k
                    );
                }
                return false;
            }
        }
        // The source up to `\end{tikzpicture}`.
        let Level::Text(t) = &mut self.input.stack[level_index] else {
            return false;
        };
        let LineSource::File { data, pos } = &t.source else {
            return false;
        };
        let (data, pos) = (Rc::clone(data), *pos);
        let rest = line_rest(&t.buf, t.loc);
        let mut text = rest.clone();
        text.push(b'\n');
        text.extend_from_slice(&data[pos.min(data.len())..]);
        let Some(i) = end_offset(&text) else {
            return false;
        };
        if i < rest.len() {
            // On this line: its characters go.
            let n = std::str::from_utf8(&rest[..i]).map_or(0, |s| s.chars().count());
            let loc = t.loc;
            t.buf.drain(loc..loc + n);
        } else {
            // On a later line: the rest of this one goes, the lines between
            // become comments (the line numbers stay), and what comes
            // before `\end` on its line becomes spaces, which TeX skips at
            // the start of a line.
            let k = pos + (i - rest.len() - 1);
            let start = data[..k]
                .iter()
                .rposition(|&b| b == b'\n')
                .map_or(0, |p| p + 1)
                .max(pos);
            let mut new = Vec::with_capacity(data.len());
            new.extend_from_slice(&data[..pos]);
            for _ in data[pos..start].iter().filter(|&&b| b == b'\n') {
                new.extend_from_slice(b"%\n");
            }
            new.extend(std::iter::repeat_n(b' ', k - start));
            new.extend_from_slice(&data[k..]);
            t.source = LineSource::File {
                data: Rc::from(new),
                pos,
            };
            t.loc = t.buf.len();
        }
        for (name, kind, meaning) in &names {
            let cs = match kind {
                CsKind::Active(c) => self.hash.active(*c),
                CsKind::Frozen => self.hash.new_frozen(name),
                _ => self.hash.lookup_or_insert(name),
            };
            if let Some(m) = meaning {
                self.eqtb.ensure_cs(cs);
                self.eqtb.cs[cs.0 as usize].val = m.clone();
                if m.cmd != crate::cmd::Cmd::SetFont {
                    self.frozen_prims.insert(name.clone(), cs);
                }
            }
        }
        if let Some(last) = self.hash.len().checked_sub(1) {
            self.eqtb.ensure_cs(CsId(last as u32));
        }
        for (f, cs) in font_ids {
            if let Some(slot) = self.fonts.id_cs.get_mut(f) {
                *slot = cs;
            }
        }
        self.figures.replaying = Some((self.save.cur_level, key));
        true
    }

    /// After a group ends (with `aftergroup`: tokens were saved for after
    /// it): ends the recording or the replay if it was the picture's.
    pub(crate) fn check_figure_end(&mut self, aftergroup: bool) {
        if let Some((level, key)) = self.figures.replaying {
            if self.save.cur_level < level {
                self.figures.replaying = None;
                self.finish_replay(key);
            }
            return;
        }
        let Some(r) = &self.figures.active else {
            return;
        };
        if self.save.cur_level >= r.level {
            return;
        }
        if aftergroup {
            self.figures.taint("\\aftergroup at its end");
        }
        let mut r = self.figures.active.take().expect("a recording");
        let us = r.started.elapsed().as_micros() as u64;
        let mut reasons = std::mem::take(&mut r.reasons);
        let entry = if reasons.is_empty() && r.key.is_some() {
            match self.capture_figure(&r, us) {
                Ok(e) => Some(e),
                Err(why) => {
                    reasons.push(why);
                    None
                }
            }
        } else {
            None
        };
        if let (Some(e), Some(k)) = (entry, r.key) {
            if self.figures.mode == FigureMode::Verify
                && let Some(old) = self.figures.cache.get(&k)
            {
                let diff = self.figure_differences(old, &e);
                if !diff.is_empty() {
                    self.figures.mismatches.push(format!(
                        "{}:{}: {}",
                        r.file,
                        r.line,
                        diff.join(", ")
                    ));
                }
            } else {
                if std::env::var_os("RETEX_FIGURES_DEBUG").is_some() {
                    eprintln!("[figures] recorded {}:{} ({k:016x})", r.file, r.line);
                }
                if let Err(why) = self.save_figure(k, &e) {
                    reasons.push(why);
                }
                self.figures.cache.insert(k, e);
            }
        }
        if !reasons.is_empty()
            && r.key.is_some()
            && let (Some(s), Some(dir)) = (r.source, &self.figures.dir)
        {
            let _ = std::fs::create_dir_all(dir);
            let _ = std::fs::write(dir.join(format!("{s:016x}.no")), reasons.join("\n"));
        }
        self.figures.pictures.push(Picture {
            file: r.file,
            line: r.line,
            us,
            source: r.source,
            globals: r.globals.len(),
            reasons,
        });
    }

    /// What differs between two records of the same picture (`verify`).
    fn figure_differences(&self, old: &Record, new: &Record) -> Vec<&'static str> {
        let mut diff = Vec::new();
        if self.list_hash(old.nodes) != self.list_hash(new.nodes) {
            diff.push("nodes");
        }
        let same_names = old.names.len() == new.names.len()
            && old.names.iter().zip(&new.names).all(|(a, b)| {
                a.0 == b.0
                    && a.1 == b.1
                    && match (&a.2, &b.2) {
                        (Some(x), Some(y)) => x.same_as(y),
                        (None, None) => true,
                        _ => false,
                    }
            });
        if !same_names {
            diff.push("control sequences");
        }
        if old.fonts != new.fonts || old.font_ids != new.font_ids {
            diff.push("fonts");
        }
        if old.space_factor != new.space_factor {
            diff.push("space factor");
        }
        if old.globals.len() != new.globals.len()
            || old
                .globals
                .iter()
                .zip(&new.globals)
                .any(|((l1, v1), (l2, v2))| l1 != l2 || self.val_hash(v1) != self.val_hash(v2))
        {
            diff.push("global assignments");
        }
        diff
    }

    /// The hash of a node list's structure.
    fn list_hash(&self, p: NodeRef) -> u64 {
        let mut fp = Fp::default();
        self.fp_list(&mut fp, p);
        fp.get()
    }

    /// The hash of a value.
    fn val_hash(&self, v: &Val) -> u64 {
        let mut fp = Fp::default();
        self.fp_val(&mut fp, v);
        fp.get()
    }

    /// What a picture just recorded left behind, to replay it.
    fn capture_figure(&mut self, r: &Recording, us: u64) -> Result<Record, &'static str> {
        // Messages are not replayed.
        if self
            .diagnostics
            .as_ref()
            .is_some_and(|d| d.len() > r.diagnostics_len)
        {
            return Err("gives messages");
        }
        let cl = self.cur_list().clone();
        let nodes = if self.nest.len() == r.nest && cl.head == r.head {
            // The nodes after the list's tail when it began, which must
            // still be in the list.
            let mut p = cl.head;
            while p != r.tail && !p.is_null() {
                p = self.nodes.next(p);
            }
            if p.is_null() {
                return Err("changes the list before it");
            }
            self.nodes.copy_list(self.nodes.next(r.tail))
        } else if r.vertical {
            // It started its paragraph (pgfpicture's `\leavevmode`, at its
            // end), which LaTeX's paragraph hooks end and start again: not
            // replayed exactly yet (a picture in a paragraph or a formula
            // is).
            return Err("starts a paragraph");
        } else {
            return Err("changes the semantic nest");
        };
        let mut names = Vec::new();
        for i in r.hash_len..self.hash.len() {
            let cs = CsId(i as u32);
            let kind = self.hash.kind(cs).clone();
            let meaning = match kind {
                CsKind::Frozen => self.eqtb.cs.get(i).map(|s| s.val.clone()),
                CsKind::Active(_) | CsKind::Null | CsKind::Single(_) | CsKind::Multi => None,
                _ => return Err("makes internal control sequences"),
            };
            names.push((self.hash.name(cs).to_vec(), kind, meaning));
        }
        let fonts = (r.fonts_len..self.fonts.fonts.len())
            .map(|f| {
                let info = &self.fonts.fonts[f];
                (info.name.clone(), info.size)
            })
            .collect();
        let font_ids = self
            .fonts
            .id_cs
            .iter()
            .enumerate()
            .filter(|&(f, cs)| r.id_cs.get(f) != Some(cs))
            .map(|(f, &cs)| (f, cs))
            .collect();
        let mut locs: Vec<Loc> = Vec::new();
        for l in &r.globals {
            if !locs.contains(l) {
                locs.push(*l);
            }
        }
        let mut globals = Vec::with_capacity(locs.len());
        for l in locs {
            let v = match self.eqtb.get(l) {
                Val::Node(b) => Val::Node(self.nodes.copy_list(b)),
                v => v,
            };
            globals.push((l, v));
        }
        Ok(Record {
            line: r.line,
            names,
            fonts,
            font_ids,
            globals,
            space_factor: cl.space_factor,
            us,
            nodes,
        })
    }

    /// Appends a copy of the list `p` to the current list.
    fn append_copy(&mut self, p: NodeRef) {
        let mut p = self.nodes.copy_list(p);
        while !p.is_null() {
            let next = self.nodes.next(p);
            self.nodes.set_next(p, NodeRef::NULL);
            self.tail_append(p);
            p = next;
        }
    }

    /// Ends the replay of the picture with key `key`, at the end of its
    /// group: its nodes and global assignments.
    fn finish_replay(&mut self, key: u64) {
        let Some(entry) = self.figures.cache.get(&key) else {
            return;
        };
        let (nodes, globals, space_factor, us) = (
            entry.nodes,
            entry.globals.clone(),
            entry.space_factor,
            entry.us,
        );
        self.append_copy(nodes);
        for (l, v) in globals {
            let v = match v {
                Val::Node(b) => Val::Node(self.nodes.copy_list(b)),
                v => v,
            };
            self.geq_define(l, v);
        }
        self.cur_list_mut().space_factor = space_factor;
        self.figures.hits.0 += 1;
        self.figures.hits.1 += us;
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn chars(s: &str) -> Vec<u32> {
        s.chars().map(u32::from).collect()
    }

    #[test]
    fn source_up_to_the_matching_end() {
        let buf = chars("\\begin{tikzpicture}[x=1cm] % \\end{tikzpicture}\n");
        let data =
            b"\\draw (0,0);\n\\begin{tikzpicture}\\end{tikzpicture}\n\\end{tikzpicture} after\n";
        let text = picture_source(&buf, 19, data, 0).unwrap();
        assert_eq!(
            String::from_utf8(text).unwrap(),
            "[x=1cm] % \\end{tikzpicture}\n\n\\draw (0,0);\n\\begin{tikzpicture}\\end{tikzpicture}\n\\end{tikzpicture}"
        );
        assert!(picture_source(&buf, 19, b"\\draw;\n", 0).is_none());
    }
}