texplain 0.1.0

Strip LaTeX to plain text with 1:1 line mapping, so prose linters report the source line.
Documentation
//! Strip LaTeX down to the prose inside it, keeping every line where it was.
//!
//! Line N of the output is line N of the input `.tex`. Markup lines come back
//! empty and prose lines come back as prose, so a position reported against
//! the stripped text is a position in the source: an alert on line 42 is an
//! alert on line 42 of the `.tex`.
//!
//! The output contains no backslashes, no `{` or `}`, and no LaTeX commands,
//! only the human-readable text a linter such as Vale should be checking.
//!
//! # API
//!
//! | Function          | Responsibility                                      |
//! |-------------------|-----------------------------------------------------|
//! | [`strip`]         | Strip a whole document, preserving line numbers     |
//! | [`strip_reader`]  | The same, reading the source from an [`io::Read`]   |
//! | [`strip_line`]    | Per-line LaTeX parsing (commands, braces, comments) |
//! | [`is_remnant`]    | Is this line leftover markup debris, not prose?     |
//!
//! [`strip`] is the entry point most callers want.  The other two are the
//! pieces it is built from, exposed for callers assembling their own pipeline.
//!
//! [`strip`] does more than apply them line by line: it also tracks state that
//! spans lines (blanked environments, multi-line `\author`/`\title` blocks), so
//! it is not simply `strip_line` in a loop.

mod remnants;
mod strip;

use std::borrow::Cow;
use std::io;

pub use remnants::is_remnant;
pub use strip::strip_line;

/// Environments whose content should be completely blanked (not prose).
///
/// Math environments are listed exhaustively rather than by prefix: a missing
/// entry does not fail loudly, it silently feeds `f(x) = (x+a)(x+b)` to the
/// linter as if it were a sentence.
const BLANK_ENVIRONMENTS: &[&str] = &[
    // Layout and code
    "tabular",
    "tabular*",
    "tabularx",
    "algorithmic",
    "algorithm",
    "lstlisting",
    "minted",
    "verbatim",
    "verbatim*",
    "Verbatim",
    "tikzpicture",
    // Math
    "displaymath",
    "math",
    "equation",
    "equation*",
    "eqnarray",
    "eqnarray*",
    "IEEEeqnarray",
    "IEEEeqnarray*",
    "align",
    "align*",
    "aligned",
    "alignat",
    "alignat*",
    "flalign",
    "flalign*",
    "gather",
    "gather*",
    "gathered",
    "multline",
    "multline*",
    "split",
    "subequations",
    "array",
    "matrix",
    "pmatrix",
    "bmatrix",
    "Bmatrix",
    "vmatrix",
    "Vmatrix",
    "smallmatrix",
    "cases",
    // Floats and other non-prose blocks
    "quote",
    "IEEEkeywords",
    "figure",
    "figure*",
    "table",
    "table*",
    "thebibliography",
];

/// Strip a LaTeX source to plain text, preserving line numbers.
///
/// Line N of the result is line N of `source`.  Lines that held only markup
/// come back empty, so a linter alert on the result points at the same line of
/// the `.tex` file.  The result is newline-terminated, so `result.lines()`
/// yields exactly as many lines as `source.lines()`.
///
/// Each line is stripped via [`strip_line`], then blanked if [`is_remnant`]
/// says it is debris.  On top of that, [`strip`] tracks state across lines:
/// non-prose environments (see the module docs) are blanked wholesale, and
/// multi-line `\author`/`\title` blocks are followed by brace depth.
///
/// # Examples
///
/// ```
/// let tex = "Prior work~\\cite{smith2020} shows the \\textbf{naive} approach is slow.\n";
/// assert_eq!(texplain::strip(tex), "Prior work shows the naive approach is slow.\n");
/// ```
#[must_use]
pub fn strip(source: &str) -> String {
    // `Cow` so that lines needing no rewrite are slices of `source`. Only the
    // final assembly copies them.
    let mut out: Vec<Cow<'_, str>> = Vec::new();
    let mut blank_depth: u32 = 0;
    let mut brace_blank_depth: u32 = 0;
    let mut caption_depth: u32 = 0;

    for line in source.lines() {
        // Exactly one line is pushed per input line. That is the 1:1 mapping.
        // `break 'line` is how each early exit names its output.
        let rendered: Cow<'_, str> = 'line: {
            // Continuation of a multi-line command being blanked (e.g. \author{...})
            if brace_blank_depth > 0 {
                brace_blank_depth = close_brace_run(line.bytes(), brace_blank_depth);
                break 'line Cow::Borrowed("");
            }

            if let Some(offset) = starts_multiline_drop(line) {
                brace_blank_depth = close_brace_run(line.bytes().skip(offset + 1), 1);
                break 'line Cow::Borrowed("");
            }

            if begins_blank_environment(line) {
                if blank_depth == 0 {
                    append_trailing_period(&mut out);
                }
                blank_depth += 1;
            }

            if blank_depth > 0 {
                if ends_blank_environment(line) {
                    blank_depth = blank_depth.saturating_sub(1);
                    break 'line Cow::Borrowed("");
                }
                // Captions inside blanked float environments are prose the
                // linter must see. Pass them (and their continuation lines,
                // tracked by brace depth) through the normal stripper.
                if caption_depth > 0 {
                    caption_depth = update_brace_depth(line, caption_depth);
                    break 'line strip_prose(line);
                }
                // Only the text after `\caption` can hold braces, so counting
                // from there is the same as counting from the command itself.
                if let Some((_, after_caption)) = line.split_once("\\caption") {
                    caption_depth = update_brace_depth(after_caption, 0);
                    break 'line strip_prose(line);
                }
                break 'line Cow::Borrowed("");
            }

            if ends_blank_environment(line) {
                blank_depth = blank_depth.saturating_sub(1);
                break 'line Cow::Borrowed("");
            }

            strip_prose(line)
        };
        out.push(rendered);
    }

    let mut result = String::with_capacity(source.len());
    for line in &out {
        result.push_str(line);
        result.push('\n');
    }
    result
}

/// Strip a LaTeX source read from `reader`, preserving line numbers.
///
/// Convenience wrapper around [`strip`] for callers holding a file or socket
/// rather than a `&str`.  The source is read fully into memory first.
///
/// # Errors
///
/// Returns an `io::Error` if reading from `reader` fails.
pub fn strip_reader(reader: impl io::Read) -> io::Result<String> {
    Ok(strip(&io::read_to_string(reader)?))
}

/// Strip one prose line: LaTeX syntax first, then blank it if what remains is
/// only debris.
///
/// Borrows from `line` whenever [`strip_line`] does.
fn strip_prose(line: &str) -> Cow<'_, str> {
    let stripped = strip_line(line);
    if is_remnant(&stripped) { Cow::Borrowed("") } else { stripped }
}

/// Consume `bytes`, tracking `{`/`}` depth from `depth`, and stop at the `}`
/// that closes the run.  Returns the remaining depth (0 once closed).
///
/// Depth is decremented with `checked_sub` so an unbalanced `}` ends the run
/// instead of overflowing.
fn close_brace_run(bytes: impl Iterator<Item = u8>, mut depth: u32) -> u32 {
    for byte in bytes {
        match byte {
            b'{' => depth += 1,
            b'}' => {
                depth = depth.saturating_sub(1);
                if depth == 0 {
                    break;
                }
            }
            _ => {}
        }
    }
    depth
}

/// Multi-line commands whose brace-delimited argument should be blanked entirely.
///
/// These are LaTeX constructs whose `{…}` argument can span multiple lines and
/// whose content is metadata (not prose to be linted): author block, title,
/// and similar. The line-by-line stripper cannot match cross-line braces, so
/// without explicit handling the metadata leaks into the output as if it were
/// prose.
const MULTILINE_DROP_COMMANDS: &[&str] = &["\\author{", "\\title{"];

/// Track `{`/`}` balance across a line, starting from `depth`.
///
/// Backslash-escaped braces (`\{`, `\}`) do not count. The depth never
/// underflows, so stray closing braces cannot corrupt the caption state.
fn update_brace_depth(line: &str, mut depth: u32) -> u32 {
    let mut bytes = line.bytes();
    while let Some(byte) = bytes.next() {
        match byte {
            // An escape consumes whatever follows, so `\{` never opens a group.
            b'\\' => drop(bytes.next()),
            b'{' => depth += 1,
            b'}' => depth = depth.saturating_sub(1),
            _ => {}
        }
    }
    depth
}

/// If the line starts a multi-line drop command, returns the byte offset of
/// the opening `{`.
fn starts_multiline_drop(line: &str) -> Option<usize> {
    let trimmed = line.trim_start();
    let leading = line.len() - trimmed.len();
    MULTILINE_DROP_COMMANDS
        .iter()
        .find(|cmd| trimmed.starts_with(**cmd))
        // Every entry ends with `{`, so its last byte is the brace we want.
        .map(|cmd| leading + cmd.len() - 1)
}

/// Extract the environment name from a `\begin{envname}` or `\end{envname}`
/// line, borrowed from the line itself.
///
/// Returning `&'src str` rather than `String` keeps this allocation-free: every
/// caller only compares the name against [`BLANK_ENVIRONMENTS`].
fn parse_env<'src>(line: &'src str, prefix: &str) -> Option<&'src str> {
    let rest = line.trim().strip_prefix(prefix)?;
    rest.get(..rest.find('}')?)
}

/// Is this line a `\begin{…}` of an environment whose body is not prose?
fn begins_blank_environment(line: &str) -> bool {
    parse_env(line, r"\begin{").is_some_and(|env| BLANK_ENVIRONMENTS.contains(&env))
}

/// Is this line an `\end{…}` of an environment whose body is not prose?
fn ends_blank_environment(line: &str) -> bool {
    parse_env(line, r"\end{").is_some_and(|env| BLANK_ENVIRONMENTS.contains(&env))
}

/// If the last non-empty line emitted so far does not end with sentence-ending
/// punctuation, append a period so that a blanked environment creates a
/// sentence break rather than fusing the prose on either side of it.
///
/// This edits that line in place.  An earlier version appended to the output
/// buffer after trimming its trailing whitespace, which silently deleted the
/// newlines already emitted and shifted every following line up by one.
fn append_trailing_period(lines: &mut [Cow<'_, str>]) {
    let Some(last) = lines.iter_mut().rev().find(|l| !l.trim().is_empty()) else {
        return;
    };
    // Only now does a borrowed line need to become owned.
    let text = last.to_mut();
    let end = text.trim_end().len();
    text.truncate(end);
    if !text.ends_with(['.', '!', '?', ':']) {
        text.push('.');
    }
}