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
//! The node list: what a TeX list is made of, once the mouth and the expander
//! have finished with it.
//!
//! `tex.web` §133-§161. Everything the stomach packages, breaks and ships is a
//! list of these; a box is a node that HOLDS such a list, which is what makes
//! boxes nest. The types are numbered here exactly as `tex.web` numbers them
//! (§135-§159), because two of TeX's rules are stated as arithmetic on that
//! number rather than as a case analysis:
//!
//! - `precedes_break(p) == type(p) < math_node` (§148): glue is a legal
//!   breakpoint only when what precedes it is not itself discardable.
//! - `if type(p)>=rule_node then s:=0 else s:=shift_amount(p)` (§653): only a
//!   box carries a shift, and `hpack` asks the number rather than the variant.
//!
//! Writing those two as a match over variants would be a rephrasing, and a
//! rephrasing is where a port stops being one. So `type_code` exists and the
//! rules are the comparisons Knuth wrote.
//!
//! Dimensions are scaled points throughout (`crate::dimen`), never floats: a
//! box's width is an integer in TeX and the arithmetic on it is exact. The one
//! float in the whole structure is `glue_set`, and it is a float in `tex.web`
//! too (§109's `glue_ratio`).

use crate::glue::{Glue, Order};

pub mod hooks;
pub mod show;

/// A dimension, in scaled points.
pub type Scaled = i64;

/// `null_flag` (§2951): a dimension that is not there.
///
/// A rule written `\hrule` with no height has a RUNNING height, which means
/// "as tall as the box that ends up holding me". It is carried as $-2^{30}$
/// precisely so that the `max` in `hpack` ignores it without a test (§653).
pub const NULL_FLAG: Scaled = -0x4000_0000;

/// `max_dimen` (§421): the largest dimension TeX will hold, $2^{30}-1$.
pub const MAX_DIMEN: Scaled = 0x3FFF_FFFF;

/// `inf_bad` (§108): a badness that means "cannot be set".
pub const INF_BAD: i64 = 10000;

/// `inf_penalty` (§157): a penalty at or above this forbids a break.
pub const INF_PENALTY: i64 = INF_BAD;

/// `eject_penalty` (§157): a penalty at or below this forces one.
pub const EJECT_PENALTY: i64 = -INF_PENALTY;

/// `awful_bad` (§833): more than a billion demerits — worse than any real
/// break.
pub const AWFUL_BAD: i64 = 0x3FFF_FFFF;

/// `deplorable` (§974): more than `inf_bad`, less than `awful_bad`.
pub const DEPLORABLE: i64 = 100_000;

/// `ignore_depth` (§212): the `\prevdepth` that means "no baseline yet", so
/// the first box on a vertical list gets no interline glue above it.
pub const IGNORE_DEPTH: Scaled = -65_536_000;

/// Whether a box's glue is being stretched, shrunk, or neither (§135).
#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
pub enum GlueSign {
    #[default]
    Normal,
    Stretching,
    Shrinking,
}

/// What a glue node is: ordinary glue, or one of the three kinds of leaders
/// (§149). The numbering is `tex.web`'s subtype, and the ORDER matters:
/// `subtype(p)>=a_leaders` is how §656 asks whether there is a leader box to
/// take dimensions from.
#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
pub enum LeaderKind {
    /// Ordinary glue.
    #[default]
    Normal,
    /// `\leaders`: copies aligned to a grid fixed by the enclosing box.
    Aligned,
    /// `\cleaders`: copies centred in the space.
    Centred,
    /// `\xleaders`: copies with the leftover space spread between them.
    Expanded,
}

impl LeaderKind {
    /// `subtype(p)>=a_leaders` (§149).
    pub fn is_leaders(self) -> bool {
        self != LeaderKind::Normal
    }
}

/// Which `\skip` parameter a glue node came from (§149: "the subtype is set to
/// indicate the source of glue"). Carried because the page builder and
/// `\showlists` both name it, not because the arithmetic reads it.
///
/// Every §224 glue parameter is here, because `\showbox` names each of them
/// (§189's `print_skip_param(subtype(p)-1)`): `\spaceskip` is what
/// `app_space` (§1041) puts between words when it is set, and `\tabskip`
/// what an alignment puts between columns. [`GlueSource::param_code`] is
/// §149's arithmetic between the two numberings.
#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
pub enum GlueSource {
    #[default]
    Normal,
    LineSkip,
    BaselineSkip,
    ParSkip,
    LeftSkip,
    RightSkip,
    TopSkip,
    SplitTopSkip,
    ParFillSkip,
    AboveDisplaySkip,
    BelowDisplaySkip,
    AboveDisplayShortSkip,
    BelowDisplayShortSkip,
    TabSkip,
    SpaceSkip,
    XSpaceSkip,
    ThinMuSkip,
    MedMuSkip,
    ThickMuSkip,
    /// `cond_math_glue` (§149): `\nonscript`, which has no glue of its own.
    CondMath,
    /// `mu_glue` (§149): an `\mskip`, whose spec is in mu.
    MuGlue,
}

impl GlueSource {
    /// The §224 parameter number (`line_skip_code` .. `thick_mu_skip_code`)
    /// this glue came from, which is `subtype(p)-1` (§149).
    pub fn param_code(self) -> Option<usize> {
        use GlueSource::*;
        Some(match self {
            LineSkip => 0,
            BaselineSkip => 1,
            ParSkip => 2,
            AboveDisplaySkip => 3,
            BelowDisplaySkip => 4,
            AboveDisplayShortSkip => 5,
            BelowDisplayShortSkip => 6,
            LeftSkip => 7,
            RightSkip => 8,
            TopSkip => 9,
            SplitTopSkip => 10,
            TabSkip => 11,
            SpaceSkip => 12,
            XSpaceSkip => 13,
            ParFillSkip => 14,
            ThinMuSkip => 15,
            MedMuSkip => 16,
            ThickMuSkip => 17,
            Normal | CondMath | MuGlue => return None,
        })
    }

    /// The inverse of [`GlueSource::param_code`]: `new_param_glue(n)` (§152)
    /// gives its node the subtype `n+1`.
    pub fn of_param(code: usize) -> GlueSource {
        use GlueSource::*;
        match code {
            0 => LineSkip,
            1 => BaselineSkip,
            2 => ParSkip,
            3 => AboveDisplaySkip,
            4 => BelowDisplaySkip,
            5 => AboveDisplayShortSkip,
            6 => BelowDisplayShortSkip,
            7 => LeftSkip,
            8 => RightSkip,
            9 => TopSkip,
            10 => SplitTopSkip,
            11 => TabSkip,
            12 => SpaceSkip,
            13 => XSpaceSkip,
            14 => ParFillSkip,
            15 => ThinMuSkip,
            16 => MedMuSkip,
            17 => ThickMuSkip,
            _ => Normal,
        }
    }
}

/// A box: an hlist or a vlist, packaged (§135-§137).
#[derive(Clone, Debug, Default)]
pub struct BoxNode {
    pub width: Scaled,
    pub depth: Scaled,
    pub height: Scaled,
    /// How far down (hlist inside an hlist: how far down; vlist inside a
    /// vlist: how far right) this box is displaced from where it would sit.
    pub shift_amount: Scaled,
    pub list: Vec<Node>,
    /// The glue ratio `hpack`/`vpack` computed (§135). A float in `tex.web`
    /// too.
    pub glue_set: f64,
    pub glue_sign: GlueSign,
    pub glue_order: Order,
    /// `false` for an `hlist_node`, `true` for a `vlist_node`.
    pub vertical: bool,
    /// What made the box, as LuaTeX numbers an hlist's subtype
    /// (`node.subtypes("hlist")`): [`BOX_UNKNOWN`], [`BOX_LINE`], [`BOX_BOX`],
    /// [`BOX_INDENT`] and the rest. TeX82 records nothing of the kind; it is
    /// carried for the callbacks of `crate::node::hooks`.
    pub subtype: u8,
}

/// LuaTeX's hlist subtypes the stomach makes.
pub const BOX_UNKNOWN: u8 = 0;
pub const BOX_LINE: u8 = 1;
pub const BOX_BOX: u8 = 2;
pub const BOX_INDENT: u8 = 3;

impl BoxNode {
    /// `new_null_box` (§136): an empty hbox with every dimension zero.
    pub fn null() -> BoxNode {
        BoxNode::default()
    }

    /// The height plus depth, which is what a vertical list charges for a box.
    pub fn height_plus_depth(&self) -> Scaled {
        self.height + self.depth
    }
}

/// A rule (§138): a solid black rectangle, any of whose dimensions may be
/// RUNNING, meaning it takes that dimension from the box it lands in.
#[derive(Clone, Copy, Debug)]
pub struct RuleNode {
    pub width: Scaled,
    pub depth: Scaled,
    pub height: Scaled,
}

impl RuleNode {
    /// `new_rule` (§139): all three dimensions running.
    pub fn running() -> RuleNode {
        RuleNode {
            width: NULL_FLAG,
            depth: NULL_FLAG,
            height: NULL_FLAG,
        }
    }

    /// `is_running(#) == (#=null_flag)` (§138).
    pub fn is_running(d: Scaled) -> bool {
        d == NULL_FLAG
    }
}

/// An insertion (§140): material destined for a different box on whatever page
/// this list ends up on. `\footnote` is one.
#[derive(Clone, Debug)]
pub struct InsNode {
    /// The box number it goes into: `\insert⟨n⟩`.
    pub number: u8,
    /// The natural height-plus-depth of the material.
    pub height: Scaled,
    /// `\splitmaxdepth` in force when it was made.
    pub depth: Scaled,
    /// `\floatingpenalty` in force when it was made.
    pub float_cost: i64,
    /// `\splittopskip` in force when it was made.
    pub split_top_skip: Glue,
    pub list: Vec<Node>,
}

/// A glue node (§149), possibly leaders.
#[derive(Clone, Debug, Default)]
pub struct GlueNode {
    pub spec: Glue,
    pub kind: LeaderKind,
    pub source: GlueSource,
    /// The box or rule leaders replicate. `None` for ordinary glue.
    pub leader: Option<Box<Node>>,
}

impl GlueNode {
    /// Plain glue with no leaders.
    pub fn new(spec: Glue) -> GlueNode {
        GlueNode {
            spec,
            ..GlueNode::default()
        }
    }

    /// Glue that names the parameter it came from, which `\showlists` prints
    /// and the page builder's `\topskip` handling produces.
    pub fn param(spec: Glue, source: GlueSource) -> GlueNode {
        GlueNode {
            spec,
            source,
            ..GlueNode::default()
        }
    }
}

/// A character, already measured in the font that will set it.
///
/// `tex.web` keeps a `char_node` as a font-and-character pair and asks the
/// font for its dimensions inside `hpack`'s inner loop (§654). The metrics are
/// carried here instead so that packaging needs no font table: the caller has
/// a `.tfm` or an `hmtx` open and looks them up once. The arithmetic §654 does
/// with them is unchanged.
#[derive(Clone, Copy, Debug)]
pub struct CharNode {
    pub font: usize,
    pub character: char,
    pub width: Scaled,
    pub height: Scaled,
    pub depth: Scaled,
}

/// What a ligature was made of (§143): `lig_ptr`'s characters, in the
/// ligature's own font, and the two boundary bits of its subtype.
///
/// The main loop (§1035) builds one when the font's program fuses two
/// characters; `\showbox` prints the components (§193) and a hyphenation
/// pass takes the word apart again from them (§898).
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct Ligature {
    /// The original characters.
    pub components: Vec<char>,
    /// `subtype(p)>1`: an implicit left boundary character took part.
    pub left_boundary: bool,
    /// `odd(subtype(p))`: an implicit right boundary character took part.
    pub right_boundary: bool,
}

/// A discretionary break (§145): what to set before it, after it, and instead
/// of it when no break is taken.
#[derive(Clone, Debug, Default)]
pub struct DiscNode {
    pub pre_break: Vec<Node>,
    pub post_break: Vec<Node>,
    /// How many nodes after this one the break replaces.
    pub replace_count: usize,
}

/// One of §1341's three file whatsits, as a list holds it.
#[derive(Clone, Debug)]
pub struct OutNode {
    /// What §1356 displays for it: `\openout3=name`, `\write3{text}` with
    /// the text unexpanded, or `\closeout3`.
    pub display: String,
    /// The run's number for what §1374 does with it, compiled
    /// (`crate::stomach::run::out_what`).
    pub action: usize,
}

/// One item of a horizontal or vertical list (§133-§159).
#[derive(Clone, Debug)]
pub enum Node {
    Char(CharNode),
    Box(BoxNode),
    Rule(RuleNode),
    Ins(InsNode),
    /// `\mark{...}`: the token list, already expanded to text.
    Mark(String),
    /// `\vadjust{...}`: material to move to the enclosing vertical list.
    Adjust(Vec<Node>),
    /// A ligature, which behaves as the character it draws (§143). The
    /// second field is what it was made of, which `\showbox` prints and a
    /// discretionary break reconstitutes.
    Ligature(CharNode, Ligature),
    Disc(DiscNode),
    /// `\special` and friends: no dimensions, carried through.
    Whatsit(String),
    /// `\openout`, `\write` or `\closeout` without `\immediate`: one of
    /// §1341's `open_node`, `write_node` and `close_node`, which puts nothing
    /// on the page and is carried out (§1373's `out_what`) when the page
    /// holding it is shipped.
    Out(OutNode),
    /// A `math_node` (§147) before a formula (`\mathon`), holding the
    /// `\mathsurround` it reserves.
    Math(Scaled),
    /// The `math_node` after a formula (`\mathoff`, subtype `after`).
    MathOff(Scaled),
    Glue(GlueNode),
    /// `explicit` is `\kern`'s subtype (§155): an explicit kern is a legal
    /// breakpoint when glue follows it, an implicit one is not.
    Kern {
        width: Scaled,
        explicit: bool,
    },
    /// A kern of subtype `acc_kern` (§155), one of the two `make_accent`
    /// puts around an accent (§1125): a kern that is neither a breakpoint nor
    /// removable, and that ends a word for the hyphenation pass.
    AccKern(Scaled),
    Penalty(i64),
}

impl Node {
    /// `type(p)` — `tex.web`'s own numbering (§135-§159).
    ///
    /// Not decoration: §148 and §653 are stated as comparisons against it.
    pub fn type_code(&self) -> u8 {
        match self {
            Node::Box(b) if b.vertical => 1,
            Node::Box(_) => 0,
            Node::Rule(_) => 2,
            Node::Ins(_) => 3,
            Node::Mark(_) => 4,
            Node::Adjust(_) => 5,
            Node::Ligature(..) => 6,
            Node::Disc(_) => 7,
            Node::Whatsit(_) | Node::Out(_) => 8,
            Node::Math(_) | Node::MathOff(_) => 9,
            Node::Glue(_) => 10,
            Node::Kern { .. } | Node::AccKern(_) => 11,
            Node::Penalty(_) => 12,
            // A char node has no `type` field at all in `tex.web` -- the
            // pointer itself says so (`is_char_node`). Everything that asks
            // for a type has already excluded it, and 255 keeps an accidental
            // ask from reading as a box.
            Node::Char(_) => 255,
        }
    }

    /// `is_char_node(p)` (§134).
    pub fn is_char(&self) -> bool {
        matches!(self, Node::Char(_))
    }

    /// `precedes_break(p) == (type(p)<math_node)` (§148): whether glue that
    /// FOLLOWS this node is a legal breakpoint.
    pub fn precedes_break(&self) -> bool {
        self.type_code() < 9
    }

    /// `non_discardable(p)` (§148) — the same test, under the name §148 gives
    /// it when the question is whether a break throws the node away.
    pub fn non_discardable(&self) -> bool {
        self.precedes_break()
    }

    /// The shift `hpack` and `vpack` charge for this node (§653, §670).
    ///
    /// `if type(p)>=rule_node then s:=0 else s:=shift_amount(p)`: the types
    /// below `rule_node` are exactly `hlist_node` and `vlist_node`, so a box
    /// carries a shift and nothing else does.
    pub fn shift_amount(&self) -> Scaled {
        match self {
            Node::Box(b) => b.shift_amount,
            _ => 0,
        }
    }
}

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

    /// The numbering is `tex.web`'s, and the two rules that read it as
    /// arithmetic are the reason it is the numbering rather than an enum
    /// discriminant that happens to be in some order.
    #[test]
    fn type_codes_are_tex_webs_own() {
        assert_eq!(Node::Box(BoxNode::null()).type_code(), 0);
        let vbox = BoxNode {
            vertical: true,
            ..BoxNode::null()
        };
        assert_eq!(Node::Box(vbox).type_code(), 1);
        assert_eq!(Node::Rule(RuleNode::running()).type_code(), 2);
        assert_eq!(Node::Mark(String::new()).type_code(), 4);
        assert_eq!(Node::Math(0).type_code(), 9);
        assert_eq!(Node::Glue(GlueNode::default()).type_code(), 10);
        assert_eq!(
            Node::Kern {
                width: 0,
                explicit: true
            }
            .type_code(),
            11
        );
        assert_eq!(Node::Penalty(0).type_code(), 12);
    }

    /// §148: glue after a box may be broken at, glue after glue may not.
    #[test]
    fn glue_breaks_only_after_something_that_stays() {
        assert!(Node::Box(BoxNode::null()).precedes_break());
        assert!(Node::Rule(RuleNode::running()).precedes_break());
        assert!(Node::Disc(DiscNode::default()).precedes_break());
        assert!(Node::Whatsit(String::new()).precedes_break());
        assert!(!Node::Math(0).precedes_break());
        assert!(!Node::Glue(GlueNode::default()).precedes_break());
        assert!(!Node::Penalty(0).precedes_break());
    }

    /// §653: a rule has no shift, so a shifted rule is not a thing that can be
    /// asked for by accident.
    #[test]
    fn only_a_box_carries_a_shift() {
        let shifted = BoxNode {
            shift_amount: 7,
            ..BoxNode::null()
        };
        assert_eq!(Node::Box(shifted).shift_amount(), 7);
        assert_eq!(Node::Rule(RuleNode::running()).shift_amount(), 0);
    }
}