texrs 0.6.4

A TeX engine: Knuth's mouth and expander, lowered for a bytecode VM
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
//! Run a compiled chunk on fusevm.
//!
//! The only host callback this milestone needs is `\message`. It pops the
//! rendered pieces the compiler pushed and joins them, which is why a message
//! containing `\the\count0` reads the register at RUN time through a slot rather
//! than being frozen when the file was read.

use crate::compiler::ops;
use fusevm::{VMResult, Value, VM};
use std::cell::RefCell;

thread_local! {
    /// What `\message` has written, in order.
    static MESSAGES: RefCell<Vec<String>> = const { RefCell::new(Vec::new()) };
}

thread_local! {
    /// The message currently being assembled.
    static BUILDING: RefCell<String> = const { RefCell::new(String::new()) };
}

thread_local! {
    /// Whether the message being built OPENS with a report. §82's
    /// `print_err` begins with `print_nl`, which starts a fresh line rather
    /// than writing the space `\message` puts between two messages -- so such
    /// a message is written hard against the one before it, not after a space.
    static GLUED: RefCell<bool> = const { RefCell::new(false) };
}

thread_local! {
    /// The document's own text, in the order it was read.
    static TEXT: RefCell<String> = const { RefCell::new(String::new()) };
}

thread_local! {
    /// `tex.web` §311's context display for the command about to run, put here
    /// by [`b_err_site`] and read by whatever reports.
    ///
    /// A compiled engine has no input stack when a run-time error happens, so
    /// the display cannot be derived then; the lowerer takes it off the mouth
    /// and the chunk carries it.
    static ERROR_SITE: RefCell<String> = const { RefCell::new(String::new()) };
    /// Whether anything was REPORTED during the run, which is what §1335
    /// consults before printing `(see the transcript file …)`.
    static REPORTED: RefCell<bool> = const { RefCell::new(false) };
}

/// Append a run of the document's text.
fn b_text(vm: &mut VM, _argc: u8) -> Value {
    let piece = render(&vm.pop());
    TEXT.with(|t| t.borrow_mut().push_str(&piece));
    Value::Undef
}

/// Open a colour. Recorded in the text stream as a marker the typesetter
/// turns into a DVI `\special`, because the text is what carries order --
/// a colour that arrived out of order would paint the wrong words.
fn b_color_push(vm: &mut VM, _argc: u8) -> Value {
    let b = render(&vm.pop());
    let g = render(&vm.pop());
    let r = render(&vm.pop());
    TEXT.with(|t| t.borrow_mut().push_str(&format!("\u{1}{r},{g},{b}\u{2}")));
    Value::Undef
}

/// Close the innermost colour.
fn b_color_pop(_vm: &mut VM, _argc: u8) -> Value {
    TEXT.with(|t| t.borrow_mut().push('\u{3}'));
    Value::Undef
}

/// Everything the document said, and clear it for the next run.
pub fn take_text() -> String {
    TEXT.with(|t| std::mem::take(&mut *t.borrow_mut()))
}

/// Record a finished message: as a message of its own, or -- when it opens
/// with a report -- appended to the last one, with nothing between.
fn record(done: String) {
    let glued = GLUED.with(|g| std::mem::take(&mut *g.borrow_mut()));
    MESSAGES.with(|m| {
        let mut m = m.borrow_mut();
        match (glued, m.last_mut()) {
            (true, Some(last)) => last.push_str(&done),
            _ => m.push(done),
        }
    });
}

/// Append a report to the message being built; see [`GLUED`].
fn push_report(text: &str) {
    BUILDING.with(|b| {
        let mut b = b.borrow_mut();
        if b.is_empty() {
            GLUED.with(|g| *g.borrow_mut() = true);
        }
        b.push_str(text);
    });
}

/// A report the mouth or the lowerer made, carried to its place in the run.
fn b_msg_report(vm: &mut VM, _argc: u8) -> Value {
    push_report(&render(&vm.pop()));
    Value::Undef
}

/// Append one piece to the message being built.
fn b_msg_append(vm: &mut VM, _argc: u8) -> Value {
    let piece = render(&vm.pop());
    BUILDING.with(|b| b.borrow_mut().push_str(&piece));
    Value::Undef
}

/// Finish the message and record it.
fn b_msg_flush(_vm: &mut VM, _argc: u8) -> Value {
    let done = BUILDING.with(|b| std::mem::take(&mut *b.borrow_mut()));
    record(done);
    Value::Undef
}

/// How a value prints inside a message. An integer prints as TeX prints one;
/// there are no floats in this subset, so anything else is a string already.
fn render(v: &Value) -> String {
    match v {
        Value::Int(n) => n.to_string(),
        Value::Str(s) => s.to_string(),
        other => format!("{other:?}"),
    }
}

/// Run `chunk` and return the messages it wrote.
pub fn run(chunk: fusevm::Chunk) -> Result<Vec<String>, String> {
    run_with(chunk, None)
}

/// The same, with the `--dap` statement-marker builtin installed.
///
/// The tracing JIT is deliberately NOT enabled here: it compiles hot code and
/// the compiled form does not call the marker, so a debugger would silently stop
/// stopping. A debug run is an interpreted run.
pub fn run_debug(
    chunk: fusevm::Chunk,
    on_line: fn(&mut VM, u8) -> Value,
) -> Result<Vec<String>, String> {
    run_with(chunk, Some(on_line))
}

thread_local! {
    /// A fault raised inside a builtin, for [`run_with`] to surface after the VM
    /// returns.
    ///
    /// A builtin can only return a `Value`, not an error, so a failed `rustc`
    /// or a missing FFI function has nowhere to go but here: the builtin
    /// records the reason and halts the VM, and the runner turns the halt into
    /// the error the caller expects. Without it a broken `\rust{ … }` block
    /// would look like a document that simply printed nothing.
    static FAULT: RefCell<Option<String>> = const { RefCell::new(None) };
}

/// Record `msg` and stop the run.
fn fault(vm: &mut VM, msg: impl Into<String>) -> Value {
    FAULT.with(|f| *f.borrow_mut() = Some(msg.into()));
    vm.request_halt();
    Value::Undef
}

/// Report `msg` and CARRY ON — `tex.web` §82's `print_err` followed by `error`,
/// which is what all but §93's fatal conditions do.
///
/// The report is pushed onto the message being BUILT rather than recorded as a
/// message of its own, and that is the whole formatting rule: `print_ln` ends
/// the error's context display and adds no character, so the `\message` that
/// follows begins hard against it on the same terminal line. It is the same
/// arrangement `lower.rs`'s `reports` makes for an error the mouth reported;
/// this is the run-time half, so that a `\multiply` overflow and a `\count`
/// constant that is too big read identically.
fn report(msg: &str) {
    let site = ERROR_SITE.with(|s| s.borrow().clone());
    REPORTED.with(|r| *r.borrow_mut() = true);
    push_report(&format!("! {msg}.{}", site.replace('\n', "")));
}

/// Record where the command about to run would be reported from. One argument.
fn b_err_site(vm: &mut VM, _argc: u8) -> Value {
    let site = render(&vm.pop());
    ERROR_SITE.with(|s| *s.borrow_mut() = site);
    Value::Int(0)
}

/// §1335: the transcript note, written only if the run reported something.
///
/// The `)` in front of it is the document's own closing paren, which tex writes
/// when the file ends and which is otherwise the last character of the run.
fn b_transcript_notice(_vm: &mut VM, _argc: u8) -> Value {
    if REPORTED.with(|r| *r.borrow()) {
        // What was held is glued (`record`); the notice is not -- tex writes the
        // closing paren after a space.
        let held = BUILDING.with(|b| std::mem::take(&mut *b.borrow_mut()));
        if !held.is_empty() {
            record(held);
        }
        MESSAGES.with(|m| {
            m.borrow_mut()
                .push(")(see the transcript file for additional information".to_string())
        });
    }
    Value::Int(0)
}

/// Compile and register a `\rust{ … }` block. One argument: the base64 body.
///
/// The error is raised on the VM rather than swallowed: a block that does not
/// compile is a broken document, and a run that quietly continued would fail
/// later at the call with a message about a missing function instead of the
/// rustc diagnostic that explains it.
fn b_ffi_compile(vm: &mut VM, _argc: u8) -> Value {
    let b64 = render(&vm.pop());
    match fusevm::ffi::compile_and_register(&b64) {
        Ok(()) => Value::Undef,
        Err(e) => fault(vm, e),
    }
}

/// Call a function a `\rust{ … }` block exported. The name is pushed first and
/// the arguments after it, so the stack is popped back to front.
fn b_ffi_call(vm: &mut VM, argc: u8) -> Value {
    let mut args = Vec::with_capacity(argc.saturating_sub(1) as usize);
    for _ in 1..argc {
        args.push(vm.pop());
    }
    args.reverse();
    let name = render(&vm.pop());
    match fusevm::ffi::try_call(&name, &args) {
        Some(Ok(v)) => v,
        Some(Err(e)) => fault(vm, e),
        // Not registered: either the block that exports it did not run, or the
        // name is misspelled. Both read the same way from here, so say both.
        None => fault(
            vm,
            format!("Undefined rust function {name} -- is its \\rust block above the call?"),
        ),
    }
}

/// `\multiply` and `\divide`, under TeX's rule rather than the machine's.
///
/// `tex.web` §1236 checks both: a product or quotient outside the 32-bit range
/// raises `Arithmetic overflow` and LEAVES THE REGISTER ALONE, and so does a
/// division by zero. Measured against tex 3.141592653: `\count1=2000000000
/// \multiply\count1 by 2` raises and the register still reads 2000000000.
///
/// The recovery is tex's too: §1236 reports through `error` rather than
/// `fatal_error`, so the run CONTINUES with the register untouched. Returning
/// the old value is what leaves it untouched -- the caller's `SetSlot` writes
/// whatever comes back, and writing the old value is a no-op.
///
/// `which` is 0 for an integer product, 1 for a quotient, and 2 for a product
/// of a dimension or glue component, which §1240 bounds at 2^30-1.
fn b_arith_checked(vm: &mut VM, _argc: u8) -> Value {
    let which = vm.pop().to_int();
    let operand = vm.pop().to_int();
    let old = vm.pop().to_int();
    let result = match which {
        0 => old.checked_mul(operand),
        2 => old
            .checked_mul(operand)
            .filter(|v| v.abs() <= crate::dimen::MAX_DIMEN),
        _ => match operand {
            0 => None,
            d => old.checked_div(d),
        },
    };
    match result {
        Some(v) if (i32::MIN as i64..=i32::MAX as i64).contains(&v) => Value::Int(v),
        _ => {
            report("Arithmetic overflow");
            Value::Int(old)
        }
    }
}

/// `tex.web` §453's `<factor><internal unit>`: the internal dimension, the
/// factor's integer part, and its fraction in 65536ths.
///
/// Cannot fail: §460 clamps an out-of-range product to the largest dimension
/// rather than raising, so there is nothing to report from here.
fn b_scale_dimen(vm: &mut VM, _argc: u8) -> Value {
    let frac = vm.pop().to_int();
    let int = vm.pop().to_int();
    let v = vm.pop().to_int();
    Value::Int(crate::dimen::scale_by_factor(int, frac, v))
}

/// Close an `\input` file: append `)` to the message already written.
///
/// Not a message of its own, because the stream is joined with spaces and tex
/// writes the paren hard against what came before it. With nothing written yet
/// the open paren IS the last message, so an empty file closes correctly too.
fn b_msg_close(_vm: &mut VM, _argc: u8) -> Value {
    MESSAGES.with(|m| {
        let mut m = m.borrow_mut();
        match m.last_mut() {
            Some(last) => last.push(')'),
            None => m.push(")".to_string()),
        }
    });
    Value::Int(0)
}

/// Append a dimension the way TeX writes one: `print_scaled`, then `pt`.
fn b_msg_dimen(vm: &mut VM, _argc: u8) -> Value {
    let sp = vm.pop().to_int();
    let text = format!("{}pt", crate::dimen::print_scaled(sp));
    BUILDING.with(|b| b.borrow_mut().push_str(&text));
    Value::Int(0)
}

/// Append a number as `\romannumeral` writes it (`tex.web` §69).
fn b_msg_roman(vm: &mut VM, _argc: u8) -> Value {
    let n = vm.pop().to_int();
    let text = crate::expand::roman_int(n);
    BUILDING.with(|b| b.borrow_mut().push_str(&text));
    Value::Int(0)
}

/// Append a glue the way TeX writes one.
fn b_msg_glue(vm: &mut VM, _argc: u8) -> Value {
    append_glue(vm, "pt")
}

/// The same in MATH units (`tex.web` §1060's `print_spec(p,"mu")`).
fn b_msg_muglue(vm: &mut VM, _argc: u8) -> Value {
    append_glue(vm, "mu")
}

fn append_glue(vm: &mut VM, unit: &str) -> Value {
    // Pushed natural, stretch, shrink, orders -- so they come back reversed.
    let orders = vm.pop().to_int();
    let shrink = vm.pop().to_int();
    let stretch = vm.pop().to_int();
    let natural = vm.pop().to_int();
    let text = crate::glue::print_glue_in(unit, natural, stretch, orders / 4, shrink, orders % 4);
    BUILDING.with(|b| b.borrow_mut().push_str(&text));
    Value::Int(0)
}

/// Install the `\message` builtins on `vm`.
///
/// Shared by the interpreted path and the AOT runtime hook: a compiled document
/// must call the same two functions the interpreted one does, or its output
/// would be a different program's.
pub fn register_message_builtins(vm: &mut VM) {
    vm.register_builtin(ops::TEXT, b_text);
    vm.register_builtin(ops::COLOR_PUSH, b_color_push);
    vm.register_builtin(ops::COLOR_POP, b_color_pop);
    vm.register_builtin(ops::MSG_APPEND, b_msg_append);
    vm.register_builtin(ops::MSG_FLUSH, b_msg_flush);
    vm.register_builtin(ops::MSG_REPORT, b_msg_report);
    vm.register_builtin(ops::MSG_CLOSE, b_msg_close);
    vm.register_builtin(ops::MSG_DIMEN, b_msg_dimen);
    vm.register_builtin(ops::MSG_ROMAN, b_msg_roman);
    vm.register_builtin(ops::MSG_GLUE, b_msg_glue);
    vm.register_builtin(ops::ARITH_CHECKED, b_arith_checked);
    vm.register_builtin(ops::SCALE_DIMEN, b_scale_dimen);
    vm.register_builtin(ops::MSG_MUGLUE, b_msg_muglue);
    vm.register_builtin(ops::ERR_SITE, b_err_site);
    vm.register_builtin(ops::TRANSCRIPT_NOTICE, b_transcript_notice);
    vm.register_builtin(ops::FFI_COMPILE, b_ffi_compile);
    vm.register_builtin(ops::FFI_CALL, b_ffi_call);
}

/// Take what `\message` has written so far, clearing the buffer.
///
/// The AOT entry needs this: fusevm runs the chunk and hands back an exit code,
/// not the messages, which live in this module's thread-local.
pub fn take_messages() -> Vec<String> {
    MESSAGES.with(|m| std::mem::take(&mut *m.borrow_mut()))
}

fn run_with(
    chunk: fusevm::Chunk,
    on_line: Option<fn(&mut VM, u8) -> Value>,
) -> Result<Vec<String>, String> {
    MESSAGES.with(|m| m.borrow_mut().clear());
    BUILDING.with(|b| b.borrow_mut().clear());
    GLUED.with(|g| *g.borrow_mut() = false);
    FAULT.with(|f| *f.borrow_mut() = None);
    ERROR_SITE.with(|s| s.borrow_mut().clear());
    REPORTED.with(|r| *r.borrow_mut() = false);
    // The decision needs the ops, and `VM::new` takes the chunk by value.
    let chunk_for_jit = chunk.clone();
    let mut vm = VM::new(chunk);
    register_message_builtins(&mut vm);
    match on_line {
        // A debug run stays interpreted. The tracing JIT compiles a hot loop
        // into native code that does not call the `DBG_LINE` marker, so a
        // debugger under it would silently stop stopping -- which is why
        // `--dap` asks for the marker builtin and gets the interpreter with it.
        Some(f) => vm.register_builtin(ops::DBG_LINE, f),
        // Everything else gets the JIT the crate has been compiling in and
        // never switching on. A TeX loop lowers to a rotated conditional back
        // edge, which is the shape fusevm's trace compiler accepts; without
        // this it recorded the trace and had nowhere to install it.
        // ... but ONLY for a chunk with a loop in it. A tracing JIT has
        // nothing to offer a straight-line program, and switching it on for one
        // is not free: fusevm 0.26.0 SEGVs in native code when three GROWING
        // loop-free documents run in one thread, which is exactly what the REPL
        // does at every prompt. `tests/jit_reentry.rs` holds the reproducer and
        // BUGS.md records it. Gating on the shape the JIT is for keeps every
        // loop at full speed and takes the crash off the path that could not
        // have used it anyway.
        None if crate::tiers::has_loop(&chunk_for_jit) => vm.enable_tracing_jit(),
        None => {}
    }
    let result = vm.run();
    // A report with nothing printed after it still has to be printed. In an
    // ordinary run the buffer is empty here -- every `\message` flushes its
    // own -- so this only ever carries an error §82 reported after the last
    // one, which tex writes on the terminal as it happens.
    let held = BUILDING.with(|b| std::mem::take(&mut *b.borrow_mut()));
    if !held.is_empty() {
        record(held);
    }
    // A builtin that faulted halted the VM, so the halt has to be read as the
    // error it stands for rather than as a clean finish.
    if let Some(f) = FAULT.with(|f| f.borrow_mut().take()) {
        return Err(f);
    }
    match result {
        VMResult::Ok(_) | VMResult::Halted => Ok(MESSAGES.with(|m| m.borrow().clone())),
        VMResult::Error(e) => Err(e),
    }
}