retex_engine/

synctex.rs

//! SyncTeX output (`\synctex`, `-synctex`): the `<job>.synctex.gz` file
//! with which editors and viewers map source lines to positions in the
//! PDF and back.
//!
//! The format is described in `man 5 synctex`. What LuaTeX records, and
//! where, comes from the files it writes (observed):
//!
//! * The file starts with a preamble (`SyncTeX Version:1`, the `Input:`
//!   lines of the files read so far, `Output:pdf`, `Magnification:`,
//!   `Unit:1` and zero offsets), then `Content:`. Each `\input` file gets
//!   the next tag; its `Input:` line names it with the current directory
//!   in front of a relative name (`/dir/./doc.tex`) and is written when
//!   the file is opened (in the preamble if no page has been shipped
//!   yet).
//! * Each page is a sheet `{n` … `}n` holding the records of its boxes.
//!   Positions are in scaled points from the top left corner of the page,
//!   with the 1in origin (`\pdfhorigin`, `\hoffset`, …) included. A box
//!   resource is written inside the sheet of the page (or form) that first
//!   uses it, after its boxes, as a sheet numbered `{n+1` … `}n` (`{1` …
//!   `}0` for an immediate one), with its bottom left corner at
//!   (0, `\pageheight`).
//! * In vertical lists only boxes are recorded: `[` for a vbox at its top
//!   left corner, `(` for an hbox at its reference point, `v`/`h` for an
//!   empty one at the bottom of the space it takes, all with their width,
//!   height and depth. In horizontal lists: boxes (empty ones at their
//!   start), glue (`g`, where it ends; rule leaders too, box leaders give
//!   their boxes), rules (`r`, where they end, with their dimensions as
//!   stored, running ones as −2³⁰), math nodes (`$`, where they are) and
//!   some kerns (`k`, see [`Synctex::kern`]). A run of glyphs gives an `x`
//!   record where it ends, with the tag and line of the last record or
//!   kern: glyphs have no fields. Marks, inserts, adjusts, boundaries and
//!   local paragraph nodes do not end a run; other nodes do.
//! * Nodes have the tag and line of the input when they were made (boxes
//!   when packaged, rules before their dimensions are scanned). Lua output
//!   and `\scantokens` text have tag 0 and count their own lines. Glue,
//!   kerns, rules and math nodes with tag or line 0 are not recorded and
//!   change nothing.
//! * `!n` records mark byte offsets (from the previous one); `Count:`
//!   gives the number of records, `x` records not included.
//!
//! The fields of the nodes are kept in [`crate::nodes::SyncFields`] while
//! SyncTeX is on.

use std::io::Write;

use crate::Engine;
use crate::input::Level;
use crate::nodes::NodeRef;
use crate::primitives_gen::assign_int as ip;

/// Tag and line.
pub type Fields = (u32, i32);

/// Where the SyncTeX data goes while the job runs.
enum Sink {
    Plain(Vec<u8>),
    /// The compressor and the bytes not given to it yet (it is fed large
    /// chunks: one write per record is slow).
    Gz(flate2::write::GzEncoder<Vec<u8>>, Vec<u8>),
}

/// The file being written.
struct Out {
    sink: Sink,
    /// Bytes written (uncompressed).
    size: u64,
    /// Offset of the last `!` record.
    last_bang: u64,
    /// Records counted for `Count:`.
    count: u64,
    /// Scratch line.
    line: Vec<u8>,
}

impl Out {
    fn emit(&mut self, counted: bool) {
        self.size += self.line.len() as u64;
        match &mut self.sink {
            Sink::Plain(v) => v.extend_from_slice(&self.line),
            Sink::Gz(g, pending) => {
                pending.extend_from_slice(&self.line);
                if pending.len() >= 1 << 16 {
                    let _ = g.write_all(pending);
                    pending.clear();
                }
            }
        }
        self.line.clear();
        if counted {
            self.count += 1;
        }
    }

    fn bang(&mut self) {
        let off = self.size - self.last_bang;
        self.last_bang = self.size;
        let _ = writeln!(self.line, "!{off}");
        self.emit(true);
    }
}

/// The SyncTeX state of a run.
#[derive(Default)]
pub struct Synctex {
    /// The `-synctex` value given on the command line: 0 forbids SyncTeX,
    /// a negative value asks for an uncompressed file.
    pub option: Option<i32>,
    /// The `Input:` names of the files read, by tag minus one.
    pub files: Vec<Vec<u8>>,
    /// The current directory, for the names of relative files.
    cwd: Option<Vec<u8>>,
    out: Option<Out>,
    /// The directory the file goes to (the PDF's), if not the output
    /// directory.
    pub dir: Option<std::path::PathBuf>,
    /// Whether a page is being shipped out (forms then get the next page
    /// number).
    in_page: bool,
    // ----- the traversal (see `kern`) -----
    /// Offset of the sheet's coordinates.
    origin: (i32, i32),
    /// Tag and line of the last record (the context of `x` records).
    ctx: Fields,
    /// The position recorded last, where kern records go.
    last: (i32, i32),
    /// Whether something was recorded in the current box since it opened.
    seen: bool,
    /// A kern not recorded yet, and its width.
    pending: Option<(Fields, i32)>,
    /// Whether glyphs were output since the last record.
    run: bool,
}

impl Synctex {
    /// The name of an input file in `Input:` lines.
    fn input_name(&mut self, path: &std::path::Path) -> Vec<u8> {
        let name = path.to_string_lossy().into_owned().into_bytes();
        if path.is_absolute() {
            return name;
        }
        let cwd = self.cwd.get_or_insert_with(|| {
            std::env::current_dir()
                .map(|d| d.to_string_lossy().into_owned().into_bytes())
                .unwrap_or_default()
        });
        let mut full = cwd.clone();
        full.push(b'/');
        full.extend_from_slice(&name);
        full
    }

    /// Registers an input file; returns its tag.
    fn add_input(&mut self, path: &std::path::Path) -> u32 {
        let name = self.input_name(path);
        let tag = self.files.len() as u32 + 1;
        if let Some(out) = self.out.as_mut() {
            out.line
                .extend_from_slice(format!("Input:{tag}:").as_bytes());
            out.line.extend_from_slice(&name);
            out.line.push(b'\n');
            out.emit(false);
        }
        self.files.push(name);
        tag
    }

    /// Opens the file (writes the preamble) if needed.
    fn open(&mut self, pdf: bool, mag: i32) -> &mut Out {
        let compressed = self.option.is_none_or(|n| n > 0);
        let files = &self.files;
        self.out.get_or_insert_with(|| {
            let sink = if compressed {
                Sink::Gz(
                    flate2::write::GzEncoder::new(Vec::new(), flate2::Compression::fast()),
                    Vec::new(),
                )
            } else {
                Sink::Plain(Vec::new())
            };
            let mut out = Out {
                sink,
                size: 0,
                last_bang: 0,
                count: 0,
                line: Vec::new(),
            };
            out.line.extend_from_slice(b"SyncTeX Version:1\n");
            for (i, f) in files.iter().enumerate() {
                out.line
                    .extend_from_slice(format!("Input:{}:", i + 1).as_bytes());
                out.line.extend_from_slice(f);
                out.line.push(b'\n');
            }
            let _ = write!(
                out.line,
                "Output:{}\nMagnification:{mag}\nUnit:1\nX Offset:0\nY Offset:0\nContent:\n",
                if pdf { "pdf" } else { "dvi" }
            );
            out.emit(false);
            out
        })
    }

    /// Starts sheet `n` with coordinates offset by `origin`.
    fn begin_sheet(&mut self, n: u32, origin: (i32, i32), pdf: bool, mag: i32) {
        let out = self.open(pdf, mag);
        out.bang();
        let _ = writeln!(out.line, "{{{n}");
        out.emit(true);
        self.origin = origin;
        self.ctx = (0, 0);
        self.last = (0, 0);
        self.seen = false;
        self.pending = None;
        self.run = false;
    }

    /// Ends sheet `n`.
    fn end_sheet(&mut self, n: u32) {
        if let Some(out) = self.out.as_mut() {
            out.bang();
            let _ = writeln!(out.line, "}}{n}");
            out.emit(true);
        }
    }

    fn out(&mut self) -> &mut Out {
        self.out.as_mut().expect("a sheet is open")
    }

    /// Writes a record `<c>tag,line:h,v` and the rest given.
    fn record(&mut self, c: u8, f: Fields, h: i32, v: i32, rest: &[i32]) {
        let (oh, ov) = self.origin;
        let out = self.out();
        out.line.push(c);
        let _ = write!(out.line, "{},{}:{},{}", f.0, f.1, h + oh, v + ov);
        for (i, x) in rest.iter().enumerate() {
            out.line.push(if i == 0 { b':' } else { b',' });
            let _ = write!(out.line, "{x}");
        }
        out.line.push(b'\n');
        out.emit(c != b'x');
    }

    /// Writes the pending kern, unless the next record has the same fields
    /// `next` (`None`: always).
    fn flush_kern(&mut self, next: Option<Fields>) {
        if let Some((f, w)) = self.pending.take()
            && Some(f) != next
        {
            let (h, v) = self.last;
            self.record(b'k', f, h, v, &[w]);
        }
    }

    /// Ends a run of glyphs at `h`: an `x` record.
    #[inline]
    pub fn end_run(&mut self, h: i32, v: i32) {
        if self.run {
            self.run = false;
            let f = self.ctx;
            self.record(b'x', f, h, v, &[]);
        }
    }

    /// A glyph.
    #[inline]
    pub fn glyph(&mut self) {
        self.run = true;
    }

    /// A box with contents opens at (`h`, `v`): its reference point for
    /// an hbox, its top left corner for a vbox.
    pub fn box_open(&mut self, hlist: bool, f: Fields, h: i32, v: i32, size: [i32; 3]) {
        self.record(if hlist { b'(' } else { b'[' }, f, h, v, &size);
        self.ctx = f;
        self.last = (h, v);
        self.seen = false;
        self.pending = None;
    }

    /// The box opened last closes; (`h`, `v`) is where its contents end:
    /// the end of the baseline of an hbox, the bottom left corner of a
    /// vbox.
    pub fn box_close(&mut self, hlist: bool, f: Fields, h: i32, v: i32) {
        let out = self.out();
        out.line.push(if hlist { b')' } else { b']' });
        out.line.push(b'\n');
        out.emit(true);
        self.ctx = f;
        self.last = (h, v);
        self.seen = true;
        self.pending = None;
    }

    /// An empty box.
    pub fn void_box(&mut self, hlist: bool, f: Fields, h: i32, v: i32, size: [i32; 3]) {
        self.flush_kern(None);
        self.record(if hlist { b'h' } else { b'v' }, f, h, v, &size);
        self.ctx = f;
        self.last = (h, v);
        self.seen = true;
    }

    /// Glue ending at `h`.
    pub fn glue(&mut self, f: Fields, h: i32, v: i32) {
        if f.0 == 0 || f.1 == 0 {
            return;
        }
        self.pending = None;
        self.record(b'g', f, h, v, &[]);
        self.ctx = f;
        self.last = (h, v);
        self.seen = true;
    }

    /// A rule ending at `h`, with its dimensions as stored.
    pub fn rule(&mut self, f: Fields, h: i32, v: i32, size: [i32; 3]) {
        if f.0 == 0 || f.1 == 0 {
            return;
        }
        self.pending = None;
        self.record(b'r', f, h, v, &size);
        self.ctx = f;
        self.last = (h, v);
        self.seen = true;
    }

    /// A math node at `h`.
    pub fn math(&mut self, f: Fields, h: i32, v: i32) {
        if f.0 == 0 || f.1 == 0 {
            return;
        }
        self.flush_kern(Some(f));
        self.record(b'$', f, h, v, &[]);
        self.ctx = f;
        self.last = (h, v);
        self.seen = true;
    }

    /// A kern of width `w`.
    ///
    /// Observed: kerns without fields (those TeX makes; copies get the
    /// current ones) are not recorded. Another kern is recorded, at the
    /// position recorded last (not where the kern is), if something was
    /// recorded in its box before and its fields differ from those of the
    /// last record; it is then preceded by the last kern not recorded, if
    /// no other record came in between. A kern not recorded waits: a
    /// following empty box, or math node with other fields, writes it too;
    /// glue, rules and boxes drop it. Either way, the kern's fields become
    /// the context of the following `x` records.
    pub fn kern(&mut self, f: Fields, w: i32) {
        if f.0 == 0 || f.1 == 0 {
            return;
        }
        if self.seen && f != self.ctx {
            self.flush_kern(Some(f));
            let (h, v) = self.last;
            self.record(b'k', f, h, v, &[w]);
        } else {
            self.pending = Some((f, w));
        }
        self.ctx = f;
        self.seen = true;
    }

    /// Writes the postamble and returns the file's content.
    fn finish(&mut self) -> Option<(Vec<u8>, bool)> {
        let mut out = self.out.take()?;
        out.bang();
        let _ = write!(out.line, "Postamble:\nCount:{}\n", out.count);
        out.emit(false);
        out.bang();
        out.line.extend_from_slice(b"Post scriptum:\n");
        out.emit(false);
        match out.sink {
            Sink::Plain(v) => Some((v, false)),
            Sink::Gz(mut g, pending) => {
                let _ = g.write_all(&pending);
                g.finish().ok().map(|v| (v, true))
            }
        }
    }
}

impl Engine {
    /// Whether SyncTeX may be used in this run (not `-synctex=0`).
    fn synctex_allowed(&self) -> bool {
        self.synctex.option != Some(0)
    }

    /// Called when the job starts and when `\synctex` changes: starts
    /// keeping the fields of nodes once `\synctex` is nonzero.
    pub fn synctex_changed(&mut self) {
        if self.eqtb.int(ip::SYNCTEX) != 0 && self.synctex_allowed() && self.nodes.sync.is_none() {
            self.nodes.enable_sync();
            self.sync_input_changed();
        }
    }

    /// Updates the current tag and line of new nodes after a change of
    /// the input (a line read, a level pushed or popped).
    #[inline]
    pub(crate) fn sync_input_changed(&mut self) {
        if let Some(s) = self.nodes.sync.as_deref_mut() {
            s.cur = self
                .input
                .stack
                .iter()
                .rev()
                .find_map(|l| match l {
                    Level::Text(t) => Some(t.sync),
                    Level::Tokens(_) => None,
                })
                .unwrap_or((0, 0));
        }
    }

    /// Gives the file just opened by `\input` (the current text level) its
    /// tag.
    pub(crate) fn synctex_input_opened(&mut self, path: &std::path::Path) {
        let tag = self.synctex.add_input(path);
        if let Some(Level::Text(t)) = self.input.stack.last_mut() {
            t.sync = (tag, 0);
        }
    }

    /// Whether the sheet about to be shipped out is recorded.
    pub(crate) fn synctex_recording(&self) -> bool {
        self.nodes.sync.is_some() && self.eqtb.int(ip::SYNCTEX) != 0
    }

    /// Starts recording a page, with the page's origin.
    pub(crate) fn synctex_begin_page(&mut self, origin: (i32, i32)) {
        let pdf = self.eqtb.int(ip::OUTPUTMODE) > 0;
        let mag = self.eqtb.int(ip::MAG);
        self.synctex
            .begin_sheet(self.total_pages + 1, origin, pdf, mag);
        self.synctex.in_page = true;
    }

    /// Ends the page.
    pub(crate) fn synctex_end_page(&mut self) {
        self.synctex.in_page = false;
        self.synctex.end_sheet(self.total_pages + 1);
    }

    /// Starts recording a box resource of height plus depth `total`.
    pub(crate) fn synctex_begin_form(&mut self, total: i32) {
        let pdf = self.eqtb.int(ip::OUTPUTMODE) > 0;
        let mag = self.eqtb.int(ip::MAG);
        let n = self.total_pages + 1 + u32::from(self.synctex.in_page);
        let page_height = self
            .eqtb
            .dimen(crate::primitives_gen::assign_dimen::PAGEHEIGHT);
        self.synctex
            .begin_sheet(n, (0, page_height - total), pdf, mag);
    }

    /// Ends a box resource.
    pub(crate) fn synctex_end_form(&mut self) {
        let n = self.total_pages + u32::from(self.synctex.in_page);
        self.synctex.end_sheet(n);
    }

    /// The SyncTeX fields of node `p`.
    #[inline]
    pub(crate) fn sync_of(&self, p: NodeRef) -> Fields {
        self.nodes.sync_fields(p)
    }

    /// Writes the SyncTeX file at the end of the job, next to the PDF, and
    /// removes a stale one (as LuaTeX does); prints `SyncTeX written on
    /// NAME.` on the terminal.
    pub(crate) fn finish_synctex(&mut self) {
        let job =
            String::from_utf8_lossy(self.job_name.as_deref().unwrap_or(b"texput")).into_owned();
        let dir = self
            .synctex
            .dir
            .clone()
            .or_else(|| self.files.output_dir.clone())
            .unwrap_or_default();
        let gz = dir.join(format!("{job}.synctex.gz"));
        let plain = dir.join(format!("{job}.synctex"));
        let result = if self.total_pages > 0 {
            self.synctex.finish()
        } else {
            None
        };
        let Some((data, compressed)) = result else {
            let _ = std::fs::remove_file(&gz);
            let _ = std::fs::remove_file(&plain);
            return;
        };
        let (path, other) = if compressed { (gz, plain) } else { (plain, gz) };
        let _ = std::fs::remove_file(&other);
        if std::fs::write(&path, &data).is_err() {
            return;
        }
        let name = path
            .file_name()
            .map(|n| n.to_string_lossy().into_owned())
            .unwrap_or_default();
        let sel = self.printer.selector;
        self.printer.selector = crate::print::Selector::TermOnly;
        self.printer.print_nl("SyncTeX written on ");
        self.printer.print_bytes(name.as_bytes());
        self.printer.print_char('.' as u32);
        self.printer.selector = sel;
    }
}