texrs 0.6.8

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
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
//! The command line, in `tex`'s own grammar.
//!
//! Every sibling frontend parses the reference tool's option grammar rather than
//! inventing one — `rubylang` mirrors MRI's `proc_options`, `phplang` mirrors
//! `php`'s — because a drop-in replacement that cannot be invoked the way the
//! thing it replaces is invoked is not a drop-in replacement. This is `tex`'s,
//! from `tex --help` and web2c's option table, plus texrs's own long options.
//!
//! The three shapes `tex(1)` accepts:
//!
//! ```text
//! tex [OPTION]... [TEXNAME[.tex]] [COMMANDS]   run a file, then more input
//! tex [OPTION]... \FIRST-LINE                  the arguments ARE the input
//! tex [OPTION]... &FMT ARGS                    with a named format
//! ```
//!
//! and the details that decide what a build script sees:
//!
//! * `TEXNAME` gets `.tex` appended when it has no extension, so `texrs doc`
//!   and `texrs doc.tex` are the same run.
//! * A first non-option argument starting with `\` makes the WHOLE argument
//!   list a line of TeX input, with no file at all — which is how a Makefile
//!   passes a one-liner.
//! * Arguments after the file are more TeX input, read after it.
//! * `-interaction=batchmode` writes nothing to the terminal.
//!
//! Options may be spelled with one dash or two (`-jobname=x`, `--jobname=x`),
//! as web2c's getopt accepts both, and a value may follow either an `=` or a
//! space.
//!
//! **Two deliberate divergences**, both from texrs taking several files where
//! `tex` takes one:
//!
//! 1. A non-option argument is a FILE unless it begins with `\`, in which case
//!    it is input — rather than tex's "the first is a file, everything after it
//!    is input". A file name beginning with a backslash is not a thing that
//!    exists; a second file to compile is.
//! 2. Options are recognised ANYWHERE, not only before the first file. tex
//!    stops parsing options at the first non-option argument, so `tex doc
//!    -halt-on-error` reads `-halt-on-error` as input to typeset. That is
//!    faithful and useless; `texrs doc -halt-on-error` sets the flag. A file
//!    genuinely named `-doc.tex` is still reachable as `./-doc.tex`.

use std::path::PathBuf;

/// What `-interaction=` selects.
///
/// texrs never stops to ask — there is no terminal interaction to have — so the
/// three non-batch modes differ only in what they would do at an error, and
/// batchmode is the one that changes observable behaviour: it silences the
/// terminal.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Interaction {
    Batch,
    NonStop,
    Scroll,
    #[default]
    ErrorStop,
}

impl Interaction {
    pub fn parse(s: &str) -> Option<Self> {
        match s {
            "batchmode" => Some(Interaction::Batch),
            "nonstopmode" => Some(Interaction::NonStop),
            "scrollmode" => Some(Interaction::Scroll),
            "errorstopmode" => Some(Interaction::ErrorStop),
            _ => None,
        }
    }

    /// Whether the terminal gets the `\message` stream at all.
    pub fn prints(self) -> bool {
        self != Interaction::Batch
    }
}

/// The one-shot modes: everything that runs instead of compiling a document.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Mode {
    Run,
    Help,
    Version,
    Repl,
    Lsp,
    Dap,
    CacheStats,
    CacheClear,
}

/// A parsed command line.
#[derive(Debug, Clone)]
pub struct Cli {
    pub mode: Mode,
    /// Files to compile, in the order given, `.tex` appended where it was left
    /// off.
    pub files: Vec<String>,
    /// TeX input from the command line itself: the `\FIRST-LINE` form, or the
    /// arguments that followed a file.
    pub commands: Vec<String>,
    /// `&FMT` or `-fmt=NAME`.
    pub format: Option<String>,

    // ---- tex's options ----------------------------------------------------
    pub interaction: Interaction,
    pub jobname: Option<String>,
    pub output_directory: Option<PathBuf>,
    pub progname: Option<String>,
    pub ini: bool,
    pub halt_on_error: bool,
    pub file_line_error: bool,
    pub recorder: bool,
    pub eight_bit: bool,

    // ---- texrs's own ------------------------------------------------------
    pub dump_tokens: bool,
    pub dump_ast: bool,
    pub disasm: bool,
    pub tiers: bool,
    pub aot: bool,
    pub build: bool,
    pub no_cache: bool,
    /// Print the document's own text rather than only its `\message` stream.
    pub text: bool,
    /// Typeset to a DVI file beside the source.
    pub dvi_out: bool,
    /// Typeset straight to a PDF, in the font the document asked for.
    pub pdf_out: bool,
    pub jobs: Option<usize>,
}

impl Default for Cli {
    fn default() -> Self {
        Self {
            mode: Mode::Run,
            files: Vec::new(),
            commands: Vec::new(),
            format: None,
            interaction: Interaction::default(),
            jobname: None,
            output_directory: None,
            progname: None,
            ini: false,
            halt_on_error: false,
            file_line_error: false,
            recorder: false,
            eight_bit: false,
            dump_tokens: false,
            dump_ast: false,
            disasm: false,
            tiers: false,
            aot: false,
            build: false,
            no_cache: false,
            text: false,
            dvi_out: false,
            pdf_out: false,
            jobs: None,
        }
    }
}

impl Cli {
    /// Whether the run is a LuaTeX by its program name or its format: `luatex`,
    /// `luahbtex`, `lualatex` and the `-dev` and `dvi` variants fmtutil.cnf
    /// builds from them all begin `lua` or `dvilua`.
    pub fn is_luatex(&self) -> bool {
        [self.progname.as_deref(), self.format.as_deref()]
            .into_iter()
            .flatten()
            .any(|n| n.starts_with("lua") || n.starts_with("dvilua"))
    }

    /// The TeX source this invocation asks for, when it came from the command
    /// line rather than a file.
    ///
    /// tex joins the arguments with spaces, which is what makes
    /// `tex '\catcode`\{=1' '\message{hi}\end'` one line rather than three.
    pub fn command_line_source(&self) -> Option<String> {
        match self.commands.is_empty() {
            true => None,
            false => Some(self.commands.join(" ")),
        }
    }
}

/// Parse an argument list (without the program name).
pub fn parse(args: &[String]) -> Result<Cli, String> {
    let mut cli = Cli::default();
    let mut i = 0;

    while i < args.len() {
        let arg = &args[i];
        i += 1;

        if !is_option(arg) {
            classify_input(&mut cli, arg);
            continue;
        }

        // `-x` and `--x` are the same option, and a value may follow an `=` or
        // a space.
        let body = arg.trim_start_matches('-');
        let (name, inline) = match body.split_once('=') {
            Some((n, v)) => (n, Some(v.to_string())),
            None => (body, None),
        };
        let mut value = |cli_name: &str| -> Result<String, String> {
            match inline.clone() {
                Some(v) => Ok(v),
                None => match args.get(i) {
                    Some(v) => {
                        i += 1;
                        Ok(v.clone())
                    }
                    None => Err(format!("texrs: {cli_name} needs a value")),
                },
            }
        };

        match name {
            // ---- one-shot modes ------------------------------------------
            "h" | "help" => cli.mode = Mode::Help,
            "version" => cli.mode = Mode::Version,
            "repl" => cli.mode = Mode::Repl,
            "lsp" => cli.mode = Mode::Lsp,
            "dap" => cli.mode = Mode::Dap,
            "cache-stats" => cli.mode = Mode::CacheStats,
            "cache-clear" => cli.mode = Mode::CacheClear,

            // ---- tex's options -------------------------------------------
            "interaction" => {
                let v = value("-interaction")?;
                cli.interaction = Interaction::parse(&v).ok_or_else(|| {
                    format!(
                        "texrs: unknown interaction mode `{v}'; use batchmode, \
                         nonstopmode, scrollmode or errorstopmode"
                    )
                })?;
            }
            "jobname" => cli.jobname = Some(value("-jobname")?),
            "output-directory" => {
                cli.output_directory = Some(PathBuf::from(value("-output-directory")?))
            }
            "progname" => cli.progname = Some(value("-progname")?),
            "fmt" => cli.format = Some(value("-fmt")?),
            "ini" => cli.ini = true,
            "halt-on-error" => cli.halt_on_error = true,
            "file-line-error" => cli.file_line_error = true,
            "no-file-line-error" => cli.file_line_error = false,
            "recorder" => cli.recorder = true,
            "8bit" => cli.eight_bit = true,

            // ---- texrs's own ---------------------------------------------
            "dump-tokens" => cli.dump_tokens = true,
            "dump-ast" => cli.dump_ast = true,
            "disasm" => cli.disasm = true,
            "tiers" => cli.tiers = true,
            "aot" => cli.aot = true,
            "build" => cli.build = true,
            "no-cache" => cli.no_cache = true,
            "text" => cli.text = true,
            "dvi" => cli.dvi_out = true,
            "pdf" => cli.pdf_out = true,
            "jobs" => {
                let v = value("--jobs")?;
                match v.parse::<usize>() {
                    Ok(n) if n >= 1 => cli.jobs = Some(n),
                    _ => return Err("texrs: --jobs needs a positive count".into()),
                }
            }

            other => return Err(format!("texrs: unknown option: -{other}")),
        }
    }
    Ok(cli)
}

/// Whether `arg` is an option rather than input.
///
/// A lone `-` is not: tex reads stdin for it. Neither is anything starting with
/// `\` or `&`, which are the two input forms.
fn is_option(arg: &str) -> bool {
    arg.len() > 1 && arg.starts_with('-') && !arg.starts_with("-\\")
}

/// File, command line, or format name.
fn classify_input(cli: &mut Cli, arg: &str) {
    if let Some(fmt) = arg.strip_prefix('&') {
        cli.format = Some(fmt.to_string());
        return;
    }
    if arg.starts_with('\\') || !cli.commands.is_empty() {
        // Once input has started on the command line it continues: `tex file
        // '\message{a}' '\end'` is one line of input after the file.
        cli.commands.push(arg.to_string());
        return;
    }
    cli.files.push(with_tex_extension(arg));
}

/// `doc` becomes `doc.tex`; `doc.tex` and `doc.cls` are left alone.
///
/// tex appends the extension only when the name has none, which is why
/// `tex doc.sty` reads `doc.sty` rather than `doc.sty.tex`.
pub fn with_tex_extension(name: &str) -> String {
    let stem = std::path::Path::new(name);
    match stem.extension().is_some() {
        true => name.to_string(),
        false => format!("{name}.tex"),
    }
}

/// The option grammar, in the fleet's house style: `── SECTION ───` dividers
/// and `//` descriptions, printed under the logo the way `tp -h` prints its own.
pub const USAGE: &str = "\
\n  USAGE: texrs [OPTIONS] [FILE[.tex]]... [COMMANDS]
         texrs [OPTIONS] \\FIRST-LINE      // the arguments are the input
         texrs [OPTIONS] &FMT ARGS        // with a named format
         texrs                            // no arguments: the prompt

  ── TEX OPTIONS ────────────────────────────────────────
  -interaction=MODE
          // batchmode, nonstopmode, scrollmode or errorstopmode
  -jobname=NAME
          // Set the job name
  -output-directory=DIR
          // Write the output there instead of beside the input
  -progname=NAME
          // Set the program name
  -fmt=NAME
          // Use a named format
  -ini
          // Be initex
  -halt-on-error
          // Stop at the first error
  -file-line-error, -no-file-line-error
          // file:line:error style messages
  -recorder
          // Record the files read
  -8bit
          // Write 8-bit characters as themselves

  ── RUNNING ────────────────────────────────────────────
  --repl
          // Start the interactive prompt
  --jobs=N
          // Compile N documents at once (default: one per core)
  --build
          // Compile into the bytecode cache and stop, without running
  --text
          // Print the document text, not only the message stream
  --dvi
          // Typeset to FILE.dvi -- total-fit lines, hyphenated
  --pdf
          // Typeset to FILE.pdf, in the font the document asked for
  --no-cache
          // Compile this run rather than reading the bytecode cache
  --aot
          // Compile the document to a standalone native executable

  ── LOOKING INSIDE ─────────────────────────────────────
  --dump-tokens
          // Print the mouth's token stream and exit
  --dump-ast
          // Print the command stream the frontend lowered to, and exit
  --disasm
          // Print the lowered fusevm bytecode and exit
  --tiers
          // Run it, then report which fusevm tier took its bytecode

  ── EDITORS ────────────────────────────────────────────
  --lsp
          // Speak the Language Server Protocol over stdio
  --dap
          // Speak the Debug Adapter Protocol over stdio

  ── CACHE ──────────────────────────────────────────────
  --cache-stats
          // Say what the bytecode cache holds and where
  --cache-clear
          // Delete it

  ── DOCUMENTS ──────────────────────────────────────────
  -X new [DIR]            // Make one (Texrs.toml + index.tex)
  -X init                 // Make one here, named after this directory
  -X build [--profile P]  // Build the document this directory is in
  -X watch [--profile P]  // Rebuild it whenever an input changes
  -X show                 // Say what the document is and can produce
  -X dump [--profile P]   // Build to stdout, writing nothing
  -X bundle fetch URL     // Download a bundle into the cache
  -X bundle list          // Say which bundles have been fetched
  -X dvi FILE.dvi         // Read what real tex shipped for a document
  -X dvi A.dvi B.dvi      // Say whether two files are the same document
  -X bib FILE.bib         // Read a bibliography database
  -X bib FILE.aux         // Say what a document cites, and what is missing
  -X bst FILE.bst         // Read a bibliography style, and check its names
  -X bibtex FILE.aux      // Run the style: write the .bbl a document reads
  -X tfm FILE.tfm [C]     // Read a font's metrics, or one character's
  -X vf FILE.vf [C]       // Read a virtual font: what it really sets
  -X pk FILE.pk [C]       // Read a packed bitmap font, and draw a character
  -X otf FILE.otf [C]     // Read an OpenType font: its tables and its cmap
  -X pfb FILE.pfb [C]     // Read a Type 1 font: its glyphs and their widths
  -X map FILE.map [NAME]  // Read a font map: what a TeX font name means
  -X enc FILE.enc         // Read an encoding: what each code is called
  -X itar FILE.tar [NAME] // Index a tar bundle, or read one file out of it
  -X special TEXT         // Say what a \\special means to a driver
  --profile NAME          // Which output to build
  --interval MS           // How often -X watch looks (default 250)

  ── SYSTEM ─────────────────────────────────────────────
  -h, --help              // Print this
  --version               // Print the version banner
";

#[cfg(test)]
mod tests {
    use super::*;

    fn cli(args: &[&str]) -> Cli {
        parse(&args.iter().map(|s| s.to_string()).collect::<Vec<_>>()).expect("parses")
    }

    #[test]
    fn a_bare_name_gets_the_tex_extension() {
        assert_eq!(cli(&["doc"]).files, vec!["doc.tex".to_string()]);
        assert_eq!(cli(&["doc.tex"]).files, vec!["doc.tex".to_string()]);
        // A name that already has an extension keeps it, whatever it is.
        assert_eq!(cli(&["doc.sty"]).files, vec!["doc.sty".to_string()]);
    }

    #[test]
    fn a_backslash_argument_makes_the_whole_line_input() {
        let c = cli(&["\\message{hi}", "\\end"]);
        assert!(c.files.is_empty(), "a line of input is not a file");
        assert_eq!(c.command_line_source().unwrap(), "\\message{hi} \\end");
    }

    #[test]
    fn arguments_after_a_file_are_input_read_after_it() {
        let c = cli(&["doc", "\\message{after}", "\\end"]);
        assert_eq!(c.files, vec!["doc.tex".to_string()]);
        assert_eq!(c.command_line_source().unwrap(), "\\message{after} \\end");
    }

    #[test]
    fn several_files_are_several_documents() {
        // tex takes one file; texrs compiles a batch, which is the one place
        // the grammar deliberately differs.
        let c = cli(&["a", "b.tex", "c"]);
        assert_eq!(c.files, vec!["a.tex", "b.tex", "c.tex"]);
    }

    #[test]
    fn options_take_one_dash_or_two_and_a_value_either_way() {
        assert_eq!(cli(&["-jobname=x", "doc"]).jobname.unwrap(), "x");
        assert_eq!(cli(&["--jobname=x", "doc"]).jobname.unwrap(), "x");
        assert_eq!(cli(&["-jobname", "x", "doc"]).jobname.unwrap(), "x");
    }

    #[test]
    fn interaction_modes_are_texs_four() {
        assert_eq!(
            cli(&["-interaction=batchmode"]).interaction,
            Interaction::Batch
        );
        assert!(!cli(&["-interaction=batchmode"]).interaction.prints());
        assert!(cli(&["-interaction=nonstopmode"]).interaction.prints());
        let err = parse(&["-interaction=loud".to_string()]).unwrap_err();
        assert!(err.contains("batchmode"), "unhelpful error: {err}");
    }

    #[test]
    fn an_option_after_the_file_is_still_an_option() {
        // tex stops parsing options at the first non-option argument, so it
        // would typeset `-halt-on-error` as text. Faithful and useless: here it
        // sets the flag, which is what someone typing it meant.
        let c = cli(&["doc", "-halt-on-error"]);
        assert_eq!(c.files, vec!["doc.tex".to_string()]);
        assert!(c.halt_on_error);
        assert!(c.commands.is_empty());
    }

    #[test]
    fn a_format_argument_is_taken_and_is_not_a_file() {
        let c = cli(&["&plain", "doc"]);
        assert_eq!(c.format.as_deref(), Some("plain"));
        assert_eq!(c.files, vec!["doc.tex".to_string()]);
        assert_eq!(cli(&["-fmt=plain", "doc"]).format.as_deref(), Some("plain"));
    }

    #[test]
    fn texs_flags_are_accepted_rather_than_refused() {
        // A build script passes these to every engine it drives; refusing them
        // would make texrs undroppable into one, even though the milestone acts
        // on almost none of them.
        let c = cli(&[
            "-ini",
            "-halt-on-error",
            "-file-line-error",
            "-recorder",
            "-8bit",
            "-output-directory=out",
            "-progname=texrs",
            "doc",
        ]);
        assert!(c.ini && c.halt_on_error && c.file_line_error && c.recorder && c.eight_bit);
        assert_eq!(c.output_directory.unwrap().to_str().unwrap(), "out");
        assert_eq!(c.progname.as_deref(), Some("texrs"));
        assert_eq!(c.files, vec!["doc.tex".to_string()]);
    }

    #[test]
    fn an_unknown_option_is_still_refused() {
        let err = parse(&["--nope".to_string()]).unwrap_err();
        assert!(err.contains("unknown option"), "{err}");
    }

    #[test]
    fn no_file_line_error_turns_the_flag_back_off() {
        assert!(!cli(&["-file-line-error", "-no-file-line-error", "doc"]).file_line_error);
    }
}