retex_engine/

print.rs

//! Low-level output: terminal, log file, strings and `\write` streams.
//!
//! This follows TeX's printing model (*TeX: The Program* §54–§71): a
//! `selector` chooses the destinations. Terminal and log lines are broken
//! after `max_print_line` characters. The current `\newlinechar` starts a
//! new line.
//!
//! Character representation, as LuaTeX prints it to the terminal and log:
//! characters below 32 appear in `^^` notation (`^^A`), except tab (9),
//! line feed (10) and carriage return (13), which are output raw, like 127.
//! Characters ≥ 128 are output as UTF-8. Line lengths count bytes, but a
//! multi-byte character is never split across lines. `\write` files and
//! strings receive raw UTF-8.

use std::io::Write;

use crate::utf8x;

/// Where printed text goes (TeX's `selector`).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Selector {
    /// Discard output.
    NoPrint,
    /// Terminal only.
    TermOnly,
    /// Log file only.
    LogOnly,
    /// Terminal and log file.
    TermAndLog,
    /// The pseudo-printing buffer used by `show_context`.
    Pseudo,
    /// Append to the string under construction.
    NewString,
    /// A `\write` stream.
    File(u32),
}

impl Selector {
    /// TeX's `selector<pseudo` test: real output destinations where the
    /// new-line character starts a new line.
    pub fn is_output(self) -> bool {
        matches!(
            self,
            Selector::NoPrint
                | Selector::TermOnly
                | Selector::LogOnly
                | Selector::TermAndLog
                | Selector::File(_)
        )
    }
}

/// The printer state.
pub struct Printer {
    /// Current destination.
    pub selector: Selector,
    /// Characters on the current terminal line.
    pub term_offset: usize,
    /// Whether the last terminal output was an automatic line break at
    /// `max_print_line`.
    pub term_just_wrapped: bool,
    /// Characters on the current log line.
    pub file_offset: usize,
    /// Maximum line length for terminal and log.
    pub max_print_line: usize,
    /// Extra characters allowed on a log line. LuaTeX lets text printed
    /// from Lua (`texio`) and its own warnings run one character past
    /// `max_print_line` in the log, but not on the terminal.
    pub log_slack: usize,
    /// Default output mode: nothing is written to the terminal, but line
    /// positions are tracked as if it were, so the log is unchanged.
    pub term_quiet: bool,
    /// While `Some`, the text printed to the terminal or log is also
    /// collected here (used to turn error messages into diagnostics).
    pub capture: Option<Vec<u8>>,
    /// Width of error context lines.
    pub error_line: usize,
    /// Width of the first half of an error context line.
    pub half_error_line: usize,
    /// Characters printed so far in the current pseudo-print or other
    /// counted operation (TeX's `tally`).
    pub tally: usize,
    /// Buffer for pseudo printing (bytes).
    pub trick_buf: Vec<u8>,
    /// Limit of pseudo-printed characters to keep.
    pub trick_count: usize,
    /// The tally at the start of the second line of pseudo printing.
    pub first_count: usize,
    /// The string under construction (`NewString`).
    pub cur_string: Vec<u8>,
    /// The current `\newlinechar` (−1 for none).
    pub new_line_char: i32,
    /// The terminal.
    term: Box<dyn Write>,
    /// The log file, once opened.
    log: Option<Box<dyn Write>>,
    /// `\write` streams that are open, by stream number.
    write_files: Vec<Option<Box<dyn Write>>>,
}

impl std::fmt::Debug for Printer {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Printer")
            .field("selector", &self.selector)
            .field("term_offset", &self.term_offset)
            .field("file_offset", &self.file_offset)
            .finish_non_exhaustive()
    }
}

impl Printer {
    /// A printer writing to `term`.
    pub fn new(term: Box<dyn Write>) -> Self {
        Printer {
            selector: Selector::TermOnly,
            term_offset: 0,
            term_just_wrapped: false,
            file_offset: 0,
            max_print_line: 79,
            log_slack: 0,
            term_quiet: false,
            capture: None,
            error_line: 79,
            half_error_line: 50,
            tally: 0,
            trick_buf: Vec::new(),
            trick_count: 0,
            first_count: 0,
            cur_string: Vec::new(),
            new_line_char: -1,
            term,
            log: None,
            write_files: Vec::new(),
        }
    }

    /// Installs the log file.
    pub fn set_log(&mut self, log: Box<dyn Write>) {
        self.log = Some(log);
    }

    /// Whether a log file is open.
    pub fn log_opened(&self) -> bool {
        self.log.is_some()
    }

    /// Flushes and closes the log file.
    pub fn close_log(&mut self) {
        if let Some(mut log) = self.log.take() {
            let _ = log.flush();
        }
    }

    /// Writes raw bytes to the log without bookkeeping (for banners).
    pub fn log_raw(&mut self, bytes: &[u8]) {
        if let Some(log) = self.log.as_mut() {
            let _ = log.write_all(bytes);
        }
    }

    /// Writes raw bytes to the terminal without bookkeeping.
    pub fn term_raw(&mut self, bytes: &[u8]) {
        let _ = self.term.write_all(bytes);
    }

    /// Flushes the terminal (TeX's `update_terminal`).
    pub fn update_terminal(&mut self) {
        let _ = self.term.flush();
    }

    /// Opens `\write` stream `n` on `w`.
    pub fn open_write(&mut self, n: u32, w: Box<dyn Write>) {
        let n = n as usize;
        if self.write_files.len() <= n {
            self.write_files.resize_with(n + 1, || None);
        }
        self.write_files[n] = Some(w);
    }

    /// The `\write` streams that are open.
    pub fn open_write_streams(&self) -> Vec<u32> {
        (0..self.write_files.len() as u32)
            .filter(|&n| self.write_files[n as usize].is_some())
            .collect()
    }

    /// Closes `\write` stream `n`.
    pub fn close_write(&mut self, n: u32) {
        if let Some(slot) = self.write_files.get_mut(n as usize)
            && let Some(mut w) = slot.take()
        {
            let _ = w.flush();
        }
    }

    /// Whether `\write` stream `n` is open.
    pub fn write_open(&self, n: u32) -> bool {
        matches!(self.write_files.get(n as usize), Some(Some(_)))
    }

    fn wterm(&mut self, b: &[u8]) {
        if !self.term_quiet {
            let _ = self.term.write_all(b);
        }
    }

    fn wlog(&mut self, b: &[u8]) {
        if let Some(log) = self.log.as_mut() {
            let _ = log.write_all(b);
        }
    }

    /// Ends the current line (TeX's `print_ln`).
    pub fn print_ln(&mut self) {
        if let Some(c) = self.capture.as_mut()
            && matches!(
                self.selector,
                Selector::TermAndLog | Selector::TermOnly | Selector::LogOnly
            )
        {
            c.push(b'\n');
        }
        match self.selector {
            Selector::TermAndLog => {
                self.wterm(b"\n");
                self.wlog(b"\n");
                self.term_offset = 0;
                self.file_offset = 0;
            }
            Selector::LogOnly => {
                self.wlog(b"\n");
                self.file_offset = 0;
            }
            Selector::TermOnly => {
                self.wterm(b"\n");
                self.term_offset = 0;
            }
            Selector::NoPrint | Selector::Pseudo | Selector::NewString => {}
            Selector::File(n) => {
                if let Some(Some(w)) = self.write_files.get_mut(n as usize) {
                    let _ = w.write_all(b"\n");
                }
            }
        }
    }

    /// Outputs one printable unit (one ASCII character or the bytes of one
    /// multi-byte character) to terminal and/or log, with line breaking.
    fn put_unit(&mut self, bytes: &[u8], term: bool, log: bool) {
        let n = bytes.len();
        if term {
            if n > 1 && self.term_offset + n > self.max_print_line {
                self.wterm(b"\n");
                self.term_offset = 0;
            }
            self.wterm(bytes);
            self.term_offset += n;
            self.term_just_wrapped = false;
            if self.term_offset >= self.max_print_line {
                self.wterm(b"\n");
                self.term_offset = 0;
                self.term_just_wrapped = true;
            }
        }
        if log {
            let max = self.max_print_line + self.log_slack;
            if n > 1 && self.file_offset + n > max {
                self.wlog(b"\n");
                self.file_offset = 0;
            }
            self.wlog(bytes);
            let before = self.file_offset;
            self.file_offset += n;
            // TeX tests for equality: a line that already ran past the
            // limit (see `log_slack`) is not broken by later characters.
            if self.file_offset >= max && before < max {
                self.wlog(b"\n");
                self.file_offset = 0;
            }
        }
    }

    /// Prints character `c`, handling the new-line character and the
    /// printable representation for terminal and log.
    pub fn print_char(&mut self, c: u32) {
        if c as i32 == self.new_line_char && self.selector.is_output() {
            self.print_ln();
            return;
        }
        match self.selector {
            Selector::TermAndLog | Selector::TermOnly | Selector::LogOnly => {
                if let Some(cap) = self.capture.as_mut() {
                    utf8x::push(cap, c);
                }
                let (term, log) = match self.selector {
                    Selector::TermAndLog => (true, true),
                    Selector::TermOnly => (true, false),
                    _ => (false, true),
                };
                if c < 32 && c != 9 && c != 10 && c != 13 {
                    for b in [b'^', b'^', (c + 64) as u8] {
                        self.put_unit(&[b], term, log);
                    }
                } else if c < 128 {
                    self.put_unit(&[c as u8], term, log);
                } else {
                    let e = utf8x::encode(c);
                    self.put_unit(&e, term, log);
                }
            }
            Selector::NoPrint => {}
            Selector::Pseudo => {
                if c < 32 && c != 9 && c != 10 && c != 13 {
                    for b in [b'^', b'^', (c + 64) as u8] {
                        self.pseudo_byte(b);
                    }
                    return;
                }
                let e = utf8x::encode(c);
                for b in e {
                    self.pseudo_byte(b);
                }
                return;
            }
            Selector::NewString => utf8x::push(&mut self.cur_string, c),
            Selector::File(n) => {
                let e = utf8x::encode(c);
                if let Some(Some(w)) = self.write_files.get_mut(n as usize) {
                    let _ = w.write_all(&e);
                }
            }
        }
        self.tally += 1;
    }

    fn pseudo_byte(&mut self, b: u8) {
        if self.tally < self.trick_count {
            let i = self.tally % self.error_line;
            if self.trick_buf.len() <= i {
                self.trick_buf.resize(i + 1, b' ');
            }
            self.trick_buf[i] = b;
        }
        self.tally += 1;
    }

    /// Prints an ASCII string (e.g. a fixed message).
    pub fn print_str(&mut self, s: &str) {
        // LuaTeX prints C strings with `tprint`, which lets log lines run
        // one character past `max_print_line` (as for Lua output).
        let slack = self.log_slack;
        self.log_slack = 1;
        for c in s.chars() {
            self.print_char(c as u32);
        }
        self.log_slack = slack;
    }

    /// Prints a string returned by a Lua callback (`glyph_info`): the log
    /// gets the bytes as they are, the terminal shows control characters
    /// in `^^` notation.
    pub fn print_callback_bytes(&mut self, s: &[u8]) {
        let (term, log) = match self.selector {
            Selector::TermAndLog => (true, true),
            Selector::TermOnly => (true, false),
            Selector::LogOnly => (false, true),
            _ => {
                self.print_bytes(s);
                return;
            }
        };
        let mut i = 0;
        while i < s.len() {
            let (c, n) = utf8x::decode(s, i);
            let unit = &s[i..i + n];
            if log {
                self.put_unit(unit, false, true);
            }
            if term {
                if c < 32 {
                    for b in [b'^', b'^', (c + 64) as u8] {
                        self.put_unit(&[b], true, false);
                    }
                } else {
                    self.put_unit(unit, true, false);
                }
            }
            self.tally += 1;
            i += n;
        }
    }

    /// Prints digits and other characters TeX prints one by one with
    /// `print_char` (no log slack).
    pub fn print_plain(&mut self, s: &str) {
        for c in s.chars() {
            self.print_char(c as u32);
        }
    }

    /// Prints a byte string in extended UTF-8 (e.g. a control-sequence
    /// name or file name).
    pub fn print_bytes(&mut self, s: &[u8]) {
        let mut i = 0;
        while i < s.len() {
            let (c, n) = utf8x::decode(s, i);
            self.print_char(c);
            i += n;
        }
    }

    /// Prints a byte string as text coming from Lua, with LuaTeX's log line
    /// length for it (see [`log_slack`](Self::log_slack)).
    pub fn print_lua_bytes(&mut self, s: &[u8]) {
        self.log_slack = 1;
        self.print_bytes(s);
        self.log_slack = 0;
    }

    /// A LuaTeX warning, `warning  (category): message`, on a line of its
    /// own.
    pub fn luatex_warning(&mut self, category: &str, msg: &str) {
        self.print_ln();
        self.print_lua_bytes(format!("warning  ({category}): {msg}").as_bytes());
        self.print_ln();
    }

    /// Starts a new line unless at the beginning of one (TeX's `print_nl`).
    pub fn print_nl(&mut self, s: &str) {
        self.begin_line();
        self.print_str(s);
    }

    /// The test-and-newline part of `print_nl`: ends the current terminal or
    /// log line if it is not empty.
    pub fn begin_line(&mut self) {
        let term = matches!(self.selector, Selector::TermOnly | Selector::TermAndLog);
        let log = matches!(self.selector, Selector::LogOnly | Selector::TermAndLog);
        if (term && self.term_offset > 0) || (log && self.file_offset > 0) {
            self.print_ln();
        }
    }

    /// Prints a decimal integer (TeX's `print_int`).
    pub fn print_int(&mut self, n: i64) {
        self.print_plain(&n.to_string());
    }

    /// Prints a scaled value (TeX's `print_scaled`).
    pub fn print_scaled(&mut self, s: i32) {
        let mut out = String::new();
        retex_arith::print_scaled(&mut out, s);
        // LuaTeX prints the integer part with `print_int` and the
        // fraction as a C string (which may run into the log slack).
        match out.find('.') {
            Some(i) => {
                self.print_plain(&out[..i]);
                self.print_str(&out[i..]);
            }
            None => self.print_plain(&out),
        }
    }

    /// Prints `"` followed by the uppercase hexadecimal value (TeX's
    /// `print_hex`).
    pub fn print_hex(&mut self, n: i64) {
        self.print_char('"' as u32);
        self.print_plain(&format!("{n:X}"));
    }

    /// Prints a positive integer in lowercase roman numerals (TeX's
    /// `print_roman_int`).
    pub fn print_roman_int(&mut self, n: i64) {
        self.print_plain(&roman(n));
    }

    /// Takes the string built by `NewString` printing.
    pub fn take_string(&mut self) -> Vec<u8> {
        std::mem::take(&mut self.cur_string)
    }

    /// Flushes all outputs.
    pub fn flush(&mut self) {
        let _ = self.term.flush();
        if let Some(log) = self.log.as_mut() {
            let _ = log.flush();
        }
        for w in self.write_files.iter_mut().flatten() {
            let _ = w.flush();
        }
    }
}

/// Lowercase roman numerals as TeX's `print_roman_int` produces them;
/// nothing for values ≤ 0.
pub fn roman(mut n: i64) -> String {
    // TeX's algorithm, driven by the string "m2d5c2l5x2v5i".
    let table = b"m2d5c2l5x2v5i";
    let mut out = String::new();
    if n <= 0 {
        return out;
    }
    let mut j = 0usize;
    let mut v: i64 = 1000;
    loop {
        while n >= v {
            out.push(table[j] as char);
            n -= v;
        }
        if n <= 0 {
            return out;
        }
        let mut k = j + 2;
        let mut u = v / i64::from(table[k - 1] - b'0');
        if table[k - 1] == b'2' {
            k += 2;
            u /= i64::from(table[k - 1] - b'0');
        }
        if n + u >= v {
            out.push(table[k] as char);
            n += u;
        } else {
            j += 2;
            v /= i64::from(table[j - 1] - b'0');
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::cell::RefCell;
    use std::rc::Rc;

    /// A `Write` that appends to a shared buffer.
    #[derive(Clone, Default)]
    struct Shared(Rc<RefCell<Vec<u8>>>);
    impl Write for Shared {
        fn write(&mut self, b: &[u8]) -> std::io::Result<usize> {
            self.0.borrow_mut().extend_from_slice(b);
            Ok(b.len())
        }
        fn flush(&mut self) -> std::io::Result<()> {
            Ok(())
        }
    }

    #[test]
    fn romans() {
        assert_eq!(roman(1984), "mcmlxxxiv");
        assert_eq!(roman(4), "iv");
        assert_eq!(roman(9), "ix");
        assert_eq!(roman(0), "");
        assert_eq!(roman(3999), "mmmcmxcix");
    }

    #[test]
    fn control_chars_and_utf8() {
        let buf = Shared::default();
        let mut p = Printer::new(Box::new(buf.clone()));
        for c in [1, 9, 0xE9, 127] {
            p.print_char(c);
        }
        assert_eq!(&*buf.0.borrow(), "^^A\té\u{7f}".as_bytes());
    }

    #[test]
    fn wraps_without_splitting_utf8() {
        let buf = Shared::default();
        let mut p = Printer::new(Box::new(buf.clone()));
        for _ in 0..40 {
            p.print_char(0xE9);
        }
        let s = String::from_utf8(buf.0.borrow().clone()).unwrap();
        let lines: Vec<&str> = s.split('\n').collect();
        assert_eq!(lines[0].chars().count(), 39);
        assert_eq!(lines[1].chars().count(), 1);
    }
}