Skip to main content

cellix_doc/
paper.rs

1//! A LaTeX paper split over files, read as LaTeX reads it: each `\input` and `\include`
2//! followed from the root's folder, and a root found only if it really takes a file in.
3
4use std::collections::HashMap;
5use std::path::{Path, PathBuf};
6use std::rc::Rc;
7
8/// How many folders above a file its root is looked for in.
9const LEVELS_UP: usize = 3;
10
11/// How deep `\input` files are followed, past any loop.
12const DEEPEST: usize = 16;
13
14/// A line up to its `%` comment, if it has one.
15pub fn uncommented(line: &str) -> &str {
16    let bytes = line.as_bytes();
17    for (at, b) in bytes.iter().enumerate() {
18        if *b == b'%' && (at == 0 || bytes[at - 1] != b'\\') {
19            return &line[..at];
20        }
21    }
22    line
23}
24
25/// The next `\input{name}`, `\input name` or `\include{name}` in a line without its comment:
26/// where it starts, the name, and where it ends. `\includegraphics` and the like aren't one.
27pub fn next_input(line: &str) -> Option<(usize, &str, usize)> {
28    let mut from = 0;
29    while let Some(found) = line[from..].find('\\') {
30        let at = from + found;
31        let after = &line[at + 1..];
32        let len = after.bytes().take_while(u8::is_ascii_alphabetic).count();
33        if len == 0 {
34            // An escaped character, as in `\\` or `\%`.
35            from = at + 1 + after.chars().next().map_or(0, char::len_utf8);
36            continue;
37        }
38        from = at + 1 + len;
39        let command = &after[..len];
40        if command != "input" && command != "include" {
41            continue;
42        }
43        let rest = &line[from..];
44        let gap = rest.len() - rest.trim_start().len();
45        let open = from + gap;
46        if line[open..].starts_with('{') {
47            let Some(close) = line[open..].find('}').map(|c| open + c) else {
48                continue;
49            };
50            return Some((at, line[open + 1..close].trim(), close + 1));
51        }
52        // TeX's own `\input name` reads the name to the next space.
53        if command == "input" && gap > 0 {
54            let len = line[open..]
55                .find(|c: char| c.is_whitespace() || c == '}' || c == '\\')
56                .unwrap_or(line.len() - open);
57            if len > 0 {
58                return Some((at, &line[open..open + len], open + len));
59            }
60        }
61    }
62    None
63}
64
65/// Every `\input` and `\include` in a line without its comment, in order.
66pub fn inputs(line: &str) -> Vec<(usize, &str, usize)> {
67    let mut found = Vec::new();
68    let mut from = 0;
69    while let Some((at, name, end)) = next_input(&line[from..]) {
70        found.push((from + at, name, from + end));
71        from += end;
72    }
73    found
74}
75
76/// The file an `\input` names, from the folder LaTeX runs in: `name.tex` when there is one,
77/// as LaTeX tries first, or else `name` as written.
78pub fn resolve(folder: &Path, name: &str) -> PathBuf {
79    let plain = folder.join(name);
80    if name.ends_with(".tex") {
81        return plain;
82    }
83    let tex = folder.join(format!("{name}.tex"));
84    if !tex.is_file() && plain.is_file() {
85        plain
86    } else {
87        tex
88    }
89}
90
91/// Whether two paths are the same file, however they're written.
92pub fn same_file(a: &Path, b: &Path) -> bool {
93    a == b || matches!((a.canonicalize(), b.canonicalize()), (Ok(a), Ok(b)) if a == b)
94}
95
96/// A paper's files as read from the disk, each kept until its size or time of change does, so
97/// counting a long paper again as one file is typed in costs a look at each, not a read.
98#[derive(Default)]
99pub struct Files {
100    canonical: HashMap<PathBuf, PathBuf>,
101    texts: HashMap<PathBuf, (Stamp, Rc<str>)>,
102}
103
104/// When a file last changed, and its size.
105type Stamp = (Option<std::time::SystemTime>, u64);
106
107impl Files {
108    /// A file's text, read again only once it has changed.
109    pub fn text(&mut self, path: &Path) -> Option<Rc<str>> {
110        let meta = std::fs::metadata(path).ok()?;
111        let stamp = (meta.modified().ok(), meta.len());
112        if let Some((known, text)) = self.texts.get(path)
113            && *known == stamp
114            && stamp.0.is_some()
115        {
116            return Some(text.clone());
117        }
118        let text: Rc<str> = std::fs::read_to_string(path).ok()?.into();
119        self.texts.insert(path.to_path_buf(), (stamp, text.clone()));
120        Some(text)
121    }
122
123    /// The one way a file's path is written, so the same file is known however it's named.
124    pub fn canonical(&mut self, path: &Path) -> PathBuf {
125        if let Some(known) = self.canonical.get(path) {
126            return known.clone();
127        }
128        match path.canonicalize() {
129            Ok(canonical) => {
130                self.canonical.insert(path.to_path_buf(), canonical.clone());
131                canonical
132            }
133            Err(_) => path.to_path_buf(),
134        }
135    }
136}
137
138/// A paper with every file it takes in read into its place.
139pub struct Expanded {
140    pub text: String,
141    /// Each file read, once, as [`Files::canonical`] writes it.
142    pub files: Vec<PathBuf>,
143}
144
145/// Reads a paper from its root, with each `\input` and `\include` read in where it stands,
146/// as LaTeX does from the root's folder. A file in `open` is read from the text given there,
147/// as an editor holds it unsaved, not from the disk. A file that takes itself in, however
148/// indirectly, is read once.
149pub fn expand(root: &Path, open: &[(&Path, &str)], files: &mut Files) -> Expanded {
150    let open: Vec<(PathBuf, &str)> = open
151        .iter()
152        .map(|(path, text)| (files.canonical(path), *text))
153        .collect();
154    let mut walk = Walk {
155        folder: root.parent().unwrap_or(Path::new("")),
156        open: &open,
157        files,
158        read: Vec::new(),
159        stack: Vec::new(),
160    };
161    let text = walk.expand(root);
162    Expanded {
163        text,
164        files: walk.read,
165    }
166}
167
168struct Walk<'a> {
169    folder: &'a Path,
170    open: &'a [(PathBuf, &'a str)],
171    files: &'a mut Files,
172    read: Vec<PathBuf>,
173    /// The files being read in, outermost first, so a loop is seen.
174    stack: Vec<PathBuf>,
175}
176
177impl Walk<'_> {
178    fn expand(&mut self, path: &Path) -> String {
179        let canonical = self.files.canonical(path);
180        if self.stack.contains(&canonical) || self.stack.len() > DEEPEST {
181            return String::new();
182        }
183        let own: Rc<str> = match self.open.iter().find(|(p, _)| *p == canonical) {
184            Some((_, text)) => Rc::from(*text),
185            None => match self.files.text(path) {
186                Some(text) => text,
187                None => return String::new(),
188            },
189        };
190        if !self.read.contains(&canonical) {
191            self.read.push(canonical.clone());
192        }
193        self.stack.push(canonical);
194        let mut out = String::with_capacity(own.len());
195        for line in own.lines() {
196            let mut rest = uncommented(line);
197            while let Some((at, name, end)) = next_input(rest) {
198                out.push_str(&rest[..at]);
199                out.push('\n');
200                let file = resolve(self.folder, name);
201                out.push_str(&self.expand(&file));
202                out.push('\n');
203                rest = &rest[end..];
204            }
205            out.push_str(rest);
206            out.push('\n');
207        }
208        self.stack.pop();
209        out
210    }
211}
212
213/// Whether a text is a whole document, with a `\documentclass` that isn't commented out.
214pub fn is_whole(text: &str) -> bool {
215    text.lines()
216        .any(|line| uncommented(line).contains("\\documentclass"))
217}
218
219/// The whole document that takes `path` in, looked for in its folder and a few above it, no
220/// higher than a repository's top. Of several in one folder, the first by name.
221pub fn root_including(path: &Path) -> Option<PathBuf> {
222    let mut files = Files::default();
223    let target = files.canonical(path);
224    let mut place = path.parent();
225    for _ in 0..=LEVELS_UP {
226        let Some(folder) = place else {
227            break;
228        };
229        let mut candidates: Vec<PathBuf> = std::fs::read_dir(folder)
230            .into_iter()
231            .flatten()
232            .flatten()
233            .map(|e| e.path())
234            .filter(|p| p.extension().is_some_and(|e| e == "tex") && p != path)
235            .collect();
236        candidates.sort();
237        for candidate in candidates {
238            let whole = files.text(&candidate).is_some_and(|text| is_whole(&text));
239            if whole
240                && files.canonical(&candidate) != target
241                && expand(&candidate, &[], &mut files).files.contains(&target)
242            {
243                return Some(candidate);
244            }
245        }
246        if folder.join(".git").exists() {
247            break;
248        }
249        place = folder.parent().filter(|p| !p.as_os_str().is_empty());
250    }
251    None
252}
253
254#[cfg(test)]
255mod tests {
256    use super::*;
257
258    #[test]
259    fn inputs_are_found_however_they_are_written() {
260        let names = |line: &str| -> Vec<String> {
261            inputs(line).iter().map(|(_, n, _)| n.to_string()).collect()
262        };
263        assert_eq!(names("\\input{a} and \\include {b}"), ["a", "b"]);
264        assert_eq!(names("\\input intro\\par"), ["intro"]);
265        assert_eq!(
266            names("Text \\input sections/two.tex more"),
267            ["sections/two.tex"]
268        );
269        assert!(names("\\includegraphics{fig} \\inputencoding{utf8}").is_empty());
270        assert!(names("\\\\input{a} \\includeonly{b}").is_empty());
271        assert!(names("\\input").is_empty());
272        assert!(names("\\input{unclosed").is_empty());
273    }
274
275    #[test]
276    fn a_papers_files_are_read_again_only_once_they_change() {
277        let dir = tempfile::tempdir().unwrap();
278        let path = dir.path().join("intro.tex");
279        std::fs::write(&path, "one").unwrap();
280        let mut files = Files::default();
281        assert_eq!(files.text(&path).as_deref(), Some("one"));
282        // Rewritten behind its back with the same size and time: still the copy it kept.
283        let then = std::fs::metadata(&path).unwrap().modified().unwrap();
284        std::fs::write(&path, "two").unwrap();
285        let file = std::fs::File::options().write(true).open(&path).unwrap();
286        file.set_modified(then).unwrap();
287        assert_eq!(files.text(&path).as_deref(), Some("one"), "not read again");
288        let later = then + std::time::Duration::from_secs(2);
289        file.set_modified(later).unwrap();
290        assert_eq!(
291            files.text(&path).as_deref(),
292            Some("two"),
293            "changed, so read"
294        );
295        std::fs::write(&path, "three!").unwrap();
296        file.set_modified(later).unwrap();
297        assert_eq!(files.text(&path).as_deref(), Some("three!"), "a new size");
298    }
299
300    #[test]
301    fn a_name_is_tried_with_tex_first() {
302        let dir = tempfile::tempdir().unwrap();
303        std::fs::write(dir.path().join("ch.v2.tex"), "").unwrap();
304        std::fs::write(dir.path().join("fig.tikz"), "").unwrap();
305        assert_eq!(resolve(dir.path(), "ch.v2"), dir.path().join("ch.v2.tex"));
306        assert_eq!(resolve(dir.path(), "fig.tikz"), dir.path().join("fig.tikz"));
307        assert_eq!(
308            resolve(dir.path(), "intro.tex"),
309            dir.path().join("intro.tex")
310        );
311        assert_eq!(
312            resolve(dir.path(), "missing"),
313            dir.path().join("missing.tex")
314        );
315    }
316}