retex_engine/

save.rs

//! Grouping and the save stack (*TeX: The Program* §268–§284, with the
//! e-TeX tracing extensions).

use crate::Engine;
use crate::eqtb::{CodeKind, Eqtb, LEVEL_ONE, LEVEL_ZERO, Loc, Meaning, Val};
use crate::primitives_gen::assign_int as ip;
use crate::token::Token;

/// A group code (`cur_group`), numbered as `\currentgrouptype` reports.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[repr(u8)]
pub enum GroupCode {
    /// The outermost level.
    BottomLevel = 0,
    /// `{…}`.
    Simple = 1,
    /// `\hbox{…}`.
    Hbox = 2,
    /// `\hbox{…}` in vertical mode (adjusted).
    AdjustedHbox = 3,
    /// `\vbox{…}`.
    Vbox = 4,
    /// `\vtop{…}`.
    Vtop = 5,
    /// `\halign{…}`, `\valign{…}`.
    Align = 6,
    /// `\noalign{…}`.
    NoAlign = 7,
    /// The output routine.
    Output = 8,
    /// Math subformula.
    Math = 9,
    /// `\discretionary{…}{…}{…}`.
    Disc = 10,
    /// `\insert`, `\vadjust`.
    Insert = 11,
    /// `\vcenter{…}`.
    Vcenter = 12,
    /// `\mathchoice{…}…`.
    MathChoice = 13,
    /// `\begingroup…\endgroup`.
    SemiSimple = 14,
    /// `$…$`.
    MathShift = 15,
    /// `\left…\right`.
    MathLeft = 16,
    /// `\localleftbox{…}`, `\localrightbox{…}` (LuaTeX).
    LocalBox = 17,
    /// `\vsplit … to` (LuaTeX internal).
    SplitOff = 18,
    /// LuaTeX internal.
    SplitKeep = 19,
    /// LuaTeX internal: alignment preamble.
    Preamble = 20,
    /// LuaTeX internal.
    AlignSet = 21,
    /// LuaTeX internal.
    FinRow = 22,
}

/// An entry of the save stack.
#[derive(Clone, Debug)]
pub enum SaveEntry {
    /// Restore `loc` to `old`, defined at `level`.
    Restore {
        /// The location.
        loc: Loc,
        /// The saved value.
        old: Val,
        /// The level of the saved value.
        level: u16,
    },
    /// Insert a token when the group ends (`\aftergroup`).
    InsertToken(Token),
    /// A group boundary.
    Boundary {
        /// The group code of the enclosing group.
        group: GroupCode,
        /// The enclosing group's boundary index.
        boundary: usize,
        /// The line where the group started (e-TeX `saved(-1)`).
        line: i32,
    },
    /// An auxiliary saved value (TeX's `saved(k)`).
    Value(i64),
    /// The bulk form of the `Restore` entries of `\lccode c = c` (or
    /// another code table) for every `c < upto`: see
    /// [`Engine::define_codes_identity`].
    RestoreCodes {
        /// The table.
        kind: CodeKind,
        /// The table before the assignments.
        old: Box<crate::eqtb::CodeTable>,
        /// The characters assigned are `0..upto`.
        upto: u32,
    },
}

/// The save stack and grouping state.
#[derive(Debug, Clone)]
pub struct SaveStack {
    /// The stack entries.
    pub stack: Vec<SaveEntry>,
    /// Current group level (`cur_level`).
    pub cur_level: u16,
    /// Current group code (`cur_group`).
    pub cur_group: GroupCode,
    /// Index of the current group's boundary entry (`cur_boundary`).
    pub cur_boundary: usize,
}

impl Default for SaveStack {
    fn default() -> Self {
        SaveStack {
            stack: Vec::new(),
            cur_level: LEVEL_ONE,
            cur_group: GroupCode::BottomLevel,
            cur_boundary: 0,
        }
    }
}

impl Engine {
    /// Begins a new group (`new_save_level`).
    pub fn new_save_level(&mut self, c: GroupCode) {
        let line = self.input.line();
        let entry = SaveEntry::Boundary {
            group: self.save.cur_group,
            boundary: self.save.cur_boundary,
            line,
        };
        if self.save.cur_level == u16::MAX {
            self.overflow("grouping levels", i64::from(u16::MAX - 1));
        }
        self.save.cur_boundary = self.save.stack.len();
        self.save.stack.push(entry);
        self.save.cur_group = c;
        if self.eqtb.int(ip::TRACINGGROUPS) > 0 {
            self.group_trace(false);
        }
        self.save.cur_level += 1;
    }

    /// Saves the value at `loc` before it changes (`eq_save`).
    fn eq_save(&mut self, loc: Loc, level: u16) {
        let old = if level == LEVEL_ZERO {
            Val::Meaning(Meaning::UNDEFINED)
        } else {
            self.eqtb.get(loc)
        };
        self.save.stack.push(SaveEntry::Restore { loc, old, level });
    }

    /// Defines `loc` locally (`eq_define` / `eq_word_define`).
    pub fn eq_define(&mut self, loc: Loc, val: Val) {
        let tracing = self.eqtb.int(ip::TRACINGASSIGNS) > 0;
        // Fast paths for the most common locations, when no save-stack
        // entry is needed.
        if !tracing {
            let cur = self.save.cur_level;
            match (loc, &val) {
                (Loc::Code(kind, ch), Val::Int(v)) => {
                    if self.eqtb.code_table_mut(kind).define_in_place(ch, *v, cur) {
                        return;
                    }
                }
                (Loc::Count(i), Val::Int(v)) => {
                    let s = &mut self.eqtb.count[i as usize];
                    if i64::from(s.val) == *v {
                        return;
                    }
                    if s.level == cur || cur == LEVEL_ONE {
                        s.val = *v as i32;
                        s.level = cur;
                        return;
                    }
                }
                (Loc::Cs(cs), Val::Meaning(m)) if (cs.0 as usize) < self.eqtb.cs.len() => {
                    let s = &self.eqtb.cs[cs.0 as usize];
                    if s.val.same_as(m) {
                        return;
                    }
                    if s.level == cur || cur == LEVEL_ONE {
                        let Val::Meaning(m) = val else { unreachable!() };
                        self.eqtb.cs[cs.0 as usize] = crate::eqtb::Slot { val: m, level: cur };
                        return;
                    }
                }
                _ => {}
            }
        }
        if self.eqtb.holds(loc, &val) {
            if tracing {
                self.restore_trace(loc, "reassigning");
            }
            return;
        }
        if tracing {
            self.restore_trace(loc, "changing");
        }
        let cur = self.save.cur_level;
        let level = self.eqtb.level(loc);
        if level != cur && cur > LEVEL_ONE {
            self.eq_save(loc, level);
        } else if Eqtb::is_word(loc) && level != cur {
            // Word regions save whenever the level differs (cur_level is
            // level_one here, so no save entry is needed).
        }
        self.eqtb.set(loc, val, cur);
        if tracing {
            self.restore_trace(loc, "into");
        }
    }

    /// Local `\lccode c = c` (or the like for `kind`) for every `c <
    /// upto`, with the save-stack effect of the individual assignments:
    /// for natives. Only inside a group (above level one), with no
    /// `\globaldefs` and no tracing, before any other assignment to the
    /// table in this group.
    pub fn define_codes_identity(&mut self, kind: CodeKind, upto: u32) {
        let cur = self.save.cur_level;
        debug_assert!(cur > LEVEL_ONE);
        let old = self.eqtb.code_table_mut(kind).define_identity(upto, cur);
        self.save.stack.push(SaveEntry::RestoreCodes {
            kind,
            old: Box::new(old),
            upto,
        });
    }

    /// Defines `loc` globally (`geq_define` / `geq_word_define`).
    pub fn geq_define(&mut self, loc: Loc, val: Val) {
        let tracing = self.eqtb.int(ip::TRACINGASSIGNS) > 0;
        if tracing {
            self.restore_trace(loc, "globally changing");
        }
        self.eqtb.set(loc, val, LEVEL_ONE);
        if tracing {
            self.restore_trace(loc, "into");
        }
    }

    /// Defines `loc` locally or globally.
    pub fn define(&mut self, global: bool, loc: Loc, val: Val) {
        if global {
            self.geq_define(loc, val);
        } else {
            self.eq_define(loc, val);
        }
    }

    /// Saves a token for insertion at the end of the group
    /// (`save_for_after`).
    pub fn save_for_after(&mut self, t: Token) {
        if self.save.cur_level > LEVEL_ONE {
            self.save.stack.push(SaveEntry::InsertToken(t));
        }
    }

    /// Ends the current group (`unsave`).
    pub fn unsave(&mut self) {
        if self.save.cur_level <= LEVEL_ONE {
            self.confusion("curlevel");
        }
        self.save.cur_level -= 1;
        self.drop_text_dirs_above(self.save.cur_level);
        let tracing = self.eqtb.int(ip::TRACINGRESTORES) > 0;
        // \aftergroup tokens are collected and reinserted as one list, in
        // the order they were saved (e-TeX).
        let mut after: Vec<Token> = Vec::new();
        loop {
            let Some(entry) = self.save.stack.pop() else {
                self.confusion("unsave");
            };
            match entry {
                SaveEntry::Boundary {
                    group,
                    boundary,
                    line,
                } => {
                    if self.eqtb.int(ip::TRACINGGROUPS) > 0 {
                        // Trace with the ending group's state still current.
                        self.save.stack.push(SaveEntry::Boundary {
                            group,
                            boundary,
                            line,
                        });
                        self.group_trace(true);
                        self.save.stack.pop();
                    }
                    self.group_warning();
                    self.save.cur_group = group;
                    self.save.cur_boundary = boundary;
                    if !after.is_empty() {
                        after.reverse();
                        self.back_list(std::rc::Rc::from(after));
                    }
                    break;
                }
                SaveEntry::InsertToken(t) => after.push(t),
                SaveEntry::Restore { loc, old, level } => {
                    if self.eqtb.level(loc) == LEVEL_ONE {
                        // The saved value is discarded (`eq_destroy`).
                        if let (Loc::Box(n), Val::Node(b)) = (loc, &old)
                            && !b.is_null()
                            && *b != self.eqtb.boxes[n as usize].val
                        {
                            self.nodes.flush_list(*b);
                        }
                        if tracing {
                            self.restore_trace(loc, "retaining");
                        }
                    } else {
                        // The current value is discarded (`eq_destroy`).
                        if let (Loc::Box(n), Val::Node(b)) = (loc, &old) {
                            let cur = self.eqtb.boxes[n as usize].val;
                            if !cur.is_null() && cur != *b {
                                self.nodes.flush_list(cur);
                            }
                        }
                        self.eqtb.set(loc, old, level);
                        // Parameters with side effects (\newlinechar is
                        // cached by the printer) follow restores too.
                        if let Loc::IntPar(i) = loc {
                            self.int_param_changed(i);
                        }
                        if tracing {
                            self.restore_trace(loc, "restoring");
                        }
                    }
                }
                SaveEntry::Value(_) => {}
                SaveEntry::RestoreCodes { kind, old, upto } => {
                    self.eqtb.code_table_mut(kind).restore_identity(&old, upto);
                }
            }
        }
    }

    /// The line number saved with the current group boundary.
    pub fn group_line(&self) -> i32 {
        match self.save.stack.get(self.save.cur_boundary) {
            Some(SaveEntry::Boundary { line, .. }) => *line,
            _ => 0,
        }
    }

    /// Prints a description of the current group (`print_group`).
    pub fn print_group(&mut self, e: bool) {
        let p = &mut self.printer;
        match self.save.cur_group {
            GroupCode::BottomLevel => {
                p.print_str("bottom level");
                return;
            }
            GroupCode::Simple | GroupCode::SemiSimple => {
                if self.save.cur_group == GroupCode::SemiSimple {
                    p.print_str("semi ");
                }
                p.print_str("simple");
            }
            GroupCode::Hbox | GroupCode::AdjustedHbox => {
                if self.save.cur_group == GroupCode::AdjustedHbox {
                    p.print_str("adjusted ");
                }
                p.print_str("hbox");
            }
            GroupCode::Vbox => p.print_str("vbox"),
            GroupCode::Vtop => p.print_str("vtop"),
            GroupCode::Align | GroupCode::NoAlign => {
                if self.save.cur_group == GroupCode::NoAlign {
                    p.print_str("no ");
                }
                p.print_str("align");
            }
            GroupCode::Output => p.print_str("output"),
            GroupCode::Disc => p.print_str("disc"),
            GroupCode::Insert => p.print_str("insert"),
            GroupCode::Vcenter => p.print_str("vcenter"),
            GroupCode::Math
            | GroupCode::MathChoice
            | GroupCode::MathShift
            | GroupCode::MathLeft => {
                p.print_str("math");
                match self.save.cur_group {
                    GroupCode::MathChoice => p.print_str(" choice"),
                    GroupCode::MathShift => p.print_str(" shift"),
                    GroupCode::MathLeft => p.print_str(" left"),
                    _ => {}
                }
            }
            GroupCode::LocalBox => p.print_str("local box"),
            GroupCode::SplitOff => p.print_str("split off"),
            GroupCode::SplitKeep => p.print_str("split keep"),
            GroupCode::Preamble => p.print_str("preamble"),
            GroupCode::AlignSet => p.print_str("align set"),
            GroupCode::FinRow => p.print_str("fin row"),
        }
        let level = self.save.cur_level;
        let line = self.group_line();
        let p = &mut self.printer;
        p.print_str(" group (level ");
        p.print_int(i64::from(level));
        p.print_char(')' as u32);
        if line != 0 {
            p.print_str(if e { " entered at line " } else { " at line " });
            p.print_int(line.into());
        }
    }

    /// Traces entering or leaving a group (`group_trace`).
    fn group_trace(&mut self, e: bool) {
        self.begin_diagnostic();
        self.printer.print_char('{' as u32);
        self.printer
            .print_str(if e { "leaving " } else { "entering " });
        self.print_group(e);
        self.printer.print_char('}' as u32);
        self.end_diagnostic(false);
    }

    /// Traces an assignment or restoration (`restore_trace`). Observed:
    /// LuaTeX does not trace its character code tables (\catcode,
    /// \lccode, \uccode, \sfcode, \mathcode, \delcode).
    pub fn restore_trace(&mut self, loc: Loc, s: &str) {
        if matches!(loc, Loc::Cat { .. } | Loc::Code(..)) {
            return;
        }
        self.begin_diagnostic();
        self.printer.print_char('{' as u32);
        self.printer.print_str(s);
        self.printer.print_char(' ' as u32);
        self.show_eqtb(loc);
        self.printer.print_char('}' as u32);
        self.end_diagnostic(false);
    }

    /// e-TeX's warning when a group ends in a different file than it began
    /// (`group_warning`). Only active with `\tracingnesting > 0`.
    fn group_warning(&mut self) {
        // Implemented together with file-level nesting checks.
    }
}