Struct Engine 

pub struct Engine {

    pub hash: CsTable,
    pub eqtb: Eqtb,
    pub save: SaveStack,
    pub input: InputState,
    pub printer: Printer,
    pub err: ErrorState,
    pub cond: CondState,
    pub files: FileState,
    pub kpse: Option<Shared>,
    pub lua: Option<Rc<dyn LuaHost>>,
    pub cur_cmd: Cmd,
    pub cur_chr: u32,
    pub cur_cs: CsId,
    pub cur_tok: Token,
    pub cur_val: i32,
    pub cur_glue: Glue,
    pub cur_toks: Option<TokenList>,
    pub cur_val_level: ValLevel,
    pub cs: KnownCs,
    pub ini_version: bool,
    pub shell_escape: u8,
    pub format_ident: String,
    pub job_name: Option<Vec<u8>>,
    pub after_token: Token,
    pub expand_depth: u32,
    pub mode: Mode,
    pub shown_mode: Mode,
    pub format_name: String,
    pub math_124: bool,
    pub math_op_nucleus: bool,
    pub nodes: Nodes,
    pub nest: Vec<ListState>,
    pub fonts: FontTable,
    pub long_state: Cmd,
    pub def_ref_cs: CsId,
    pub runaway_list: Vec<Token>,
    pub last_cs_name: CsId,
    pub frozen_prims: HashMap<Vec<u8>, CsId>,
    pub marks: Marks,
    pub input_read_finished: bool,
    pub long_help_seen: bool,
    pub dead_cycles: i32,
    pub insert_penalties: i32,
    pub last_badness: i32,
    pub single_mac_param: bool,
    pub pack_dir: i8,
    pub random_seed: i32,
    pub randoms: Randoms,
    pub last_x_pos: i32,
    pub last_y_pos: i32,
    pub mag_set: i32,
    pub font_dimen_loc: Option<(u32, u32)>,
    pub depth_threshold: i32,
    pub breadth_max: i32,
    pub par_token_cs: CsId,
    pub dump_requested: bool,
    pub exec_context: bool,
    pub one_step: bool,
    pub origins: Option<Box<Origins>>,
    pub profiler: Option<Box<Profiler>>,
    pub start_ints: Vec<(u32, i32)>,
    pub output_comment: Option<String>,
    pub start_time: StartTime,
    pub page: PageState,
    pub lua_functions: HashMap<i32, u32>,
    pub format_hook: Option<EngineHook>,
    pub finish_hook: Option<EngineHook>,
    pub deferred_writes: Vec<(i32, TokenList)>,
    pub text_dirs: Vec<(u16, i8, i8)>,
    pub pending_forms: Vec<Vec<u32>>,
    pub form_objects: Vec<Vec<PdfObject>>,
    pub outer_text_dirs: Vec<Vec<(u16, i8, i8)>>,
    pub outer_math_dirs: Vec<(u16, i32, i32)>,
    pub written_sink: WrittenSink,
    pub ts: TsState,
    pub pending_lua_tokens: Option<Vec<Token>>,
    pub diagnostics: Option<Vec<Diagnostic>>,
    pub prompt_hook: Option<PromptHook>,
    pub progress_hook: Option<fn(&mut Engine)>,
    pub diagnostics_shown: usize,
    pub prompted: bool,
    pub images: Vec<ImageResource>,
    pub last_image_index: i32,
    pub last_image_pages: i32,
    pub svg_fonts_set: bool,
    pub box_resources: Vec<BoxResource>,
    pub last_box_index: i32,
    pub arg_scratch: Vec<Token>,
    pub param_scratch: Vec<TokenList>,
    pub write_paths: Vec<Option<PathBuf>>,
    pub snapshot_cs: Option<CsId>,
    pub snapshot_hook: Option<Hook>,
    pub page_hook: Option<fn(&mut Engine)>,
    pub final_hook: Option<fn(&mut Engine)>,
    pub fp_cache: Option<Box<FpCache>>,
    pub edit_request: Option<(Vec<u8>, i32)>,
    pub output_written: Option<(String, u32, u64)>,
    pub input_line_for_lua: i32,
    pub backend_cs: HashMap<&'static str, CsId>,
    pub local_level: u32,
    pub lua_scanned_box: Option<NodeRef>,
    pub lua_scan_waiting: bool,
    pub backend: Option<Box<dyn Backend>>,
    pub dvi: DviWriter,
    pub languages: Vec<Option<Language>>,
    pub pdf: PdfState,
    pub colorstack_values: HashMap<i32, Vec<Vec<u8>>>,
    pub total_pages: u32,
    pub math_glues: Vec<Glue>,
    pub math_params_initialized: bool,
    pub synctex: Synctex,
    /* private fields */
}

The global state of a TeX run.

Fields

hash: CsTable

Control-sequence names.

eqtb: Eqtb

The table of equivalents.

save: SaveStack

The save stack and grouping state.

input: InputState

The input stack.

printer: Printer

Terminal, log and \write output.

err: ErrorState

Error-handling state.

cond: CondState

Conditionals.

files: FileState

Files: \openin/\read, \openout, input file stack.

kpse: Option<Shared>

The file finder.

lua: Option<Rc<dyn LuaHost>>

The Lua interpreter, when available.

cur_cmd: Cmd

The current command code (cur_cmd).

cur_chr: u32

The current modifier (cur_chr).

cur_cs: CsId

The current control sequence (cur_cs); hash::NO_CS for characters.

cur_tok: Token

The current token (cur_tok).

cur_val: i32

The value most recently scanned (cur_val).

cur_glue: Glue

The glue most recently scanned, when cur_val_level is glue.

cur_toks: Option<TokenList>

The token list most recently scanned, when cur_val_level is tokens.

cur_val_level: ValLevel

The level of cur_val.

cs: KnownCs

Well-known control sequences.

ini_version: bool

Whether the run is in IniTeX mode.

shell_escape: u8

Shell escape mode (see init::Options::shell_escape).

format_ident: String

The format identification printed in the banner.

job_name: Option<Vec<u8>>

The job name, once known.

after_token: Token

Token saved by \afterassignment (after_token).

expand_depth: u32

Number of nested expansions (LuaTeX’s expand_depth_count).

mode: Mode

The current mode (copy of the innermost nest level’s mode).

shown_mode: Mode

The mode last shown by show_cur_cmd_chr.

format_name: String

The format name (\formatname).

math_124: bool

Math as LuaTeX 1.24 (TeX Live 2026) typesets it, chosen for formats of LaTeX 2026-06 and later (see Engine::load_format); else LuaTeX 1.22 (TeX Live 2025), the version retex reports.

math_op_nucleus: bool

Building an operator’s character nucleus, which gets no italic correction in OpenType math (LuaTeX 1.24 as 1.22).

nodes: Nodes

Node memory.

nest: Vec<ListState>

The semantic nest; the last entry is the current list.

fonts: FontTable

Loaded fonts.

long_state: Cmd

The long_state of the macro being called.

def_ref_cs: CsId

The control sequence being defined (for diagnostics).

runaway_list: Vec<Token>

The partial token list printed by runaway.

last_cs_name: CsId

The control sequence last made by \csname (\lastnamedcs).

frozen_prims: HashMap<Vec<u8>, CsId>

Frozen copies made by \primitive.

marks: Marks

Mark texts.

input_read_finished: bool

Set when a \read line has been consumed.

long_help_seen: bool

Whether the long \errmessage help has been shown.

dead_cycles: i32

\deadcycles.

insert_penalties: i32

\insertpenalties.

last_badness: i32

\badness.

single_mac_param: bool

Token lists show a macro parameter character once, not doubled (\luaescapestring).

pack_dir: i8

The direction the next box made by hpack or vpackage gets (from dir/bdir of a box specification), or -1. It is set before packing because over- and underfull box reports show it.

random_seed: i32

\randomseed: the seed \setrandomseed last gave (its absolute value), or the one chosen at startup.

randoms: Randoms

The state of the random number generator (METAFONT’s, see retex_arith::random) behind \uniformdeviate, \normaldeviate and the tex library’s randomizers.

last_x_pos: i32

\lastxpos.

last_y_pos: i32

\lastypos.

mag_set: i32

The magnification frozen by prepare_mag.

font_dimen_loc: Option<(u32, u32)>

The font dimension located by find_font_dimen.

depth_threshold: i32

\showboxdepth in effect while displaying boxes.

breadth_max: i32

\showboxbreadth in effect while displaying boxes.

par_token_cs: CsId

The paragraph-ending control sequence (\partokenname).

dump_requested: bool

Whether \dump ended the run.

exec_context: bool

Whether a macro expanded now would have its body executed by main control (see native).

one_step: bool

Whether the next expand is a single expansion step whose result is not expanded further (\expandafter, \span in a preamble, Lua’s token.expand): expandable native implementations do not run there (see native). expand clears it on entry.

origins: Option<Box<Origins>>

Where macros are defined (retex profile, retex explain).

profiler: Option<Box<Profiler>>

The sampling profiler (retex profile).

start_ints: Vec<(u32, i32)>

Integer parameters set from the command line when the job starts (init::Options::int_params).

output_comment: Option<String>

-output-comment.

start_time: StartTime

The job’s start time (\time, the banner, the PDF creation date).

page: PageState

The page builder.

lua_functions: HashMap<i32, u32>

Lua functions registered for \luafunction (by number).

format_hook: Option<EngineHook>

Called to store the format when \dump is executed.

finish_hook: Option<EngineHook>

Called at the end of the run to finish output files.

deferred_writes: Vec<(i32, TokenList)>

Non-immediate \writes waiting for shipout.

text_dirs: Vec<(u16, i8, i8)>

Text directions opened in the current box: (group level, direction, the text direction before), innermost last (see dirs).

pending_forms: Vec<Vec<u32>>

Box resources to write after the page or form being written, one list per open page or form.

form_objects: Vec<Vec<PdfObject>>

Objects referred to (\pdfextension refobj) in the box resources being written, one list per open form.

outer_text_dirs: Vec<Vec<(u16, i8, i8)>>

The text_dirs of the enclosing boxes.

outer_math_dirs: Vec<(u16, i32, i32)>

The math and text directions outside the open formulas, with the save level of each formula’s group.

written_sink: WrittenSink

Contents of files written by \write, for the pass driver.

ts: TsState

State of the typesetting routines.

pending_lua_tokens: Option<Vec<Token>>

Tokens printed from Lua waiting to be pushed as a token list.

diagnostics: Option<Vec<Diagnostic>>

Default output mode: errors and warnings recorded for the driver (None in compatibility mode).

prompt_hook: Option<PromptHook>

Default output mode, interactive: shows the diagnostics recorded since the last prompt, and the prompt, before the terminal is read. Returns false if it showed nothing (the error only repeats one already reported): TeX then goes on without asking.

progress_hook: Option<fn(&mut Engine)>

Default output mode: called when a page is shipped or a file opened, to show progress and the errors recorded so far.

diagnostics_shown: usize

The number of diagnostics the prompt hook has shown.

prompted: bool

Whether the terminal was read (an error or a \read prompt).

images: Vec<ImageResource>

Image resources (\saveimageresource), in the order saved (their indices are their object numbers).

last_image_index: i32

\lastsavedimageresourceindex.

last_image_pages: i32

\lastsavedimageresourcepages.

svg_fonts_set: bool

Whether SVG text has been given its font finder.

box_resources: Vec<BoxResource>

Box resources (\saveboxresource), in the order saved (their indices are their object numbers).

last_box_index: i32

\lastsavedboxresourceindex.

arg_scratch: Vec<Token>

Scratch buffer for macro arguments (reused by macro_call).

param_scratch: Vec<TokenList>

Scratch buffer for the argument list of a macro call.

write_paths: Vec<Option<PathBuf>>

The file of each \write stream opened (see snapshot).

snapshot_cs: Option<CsId>

The macro at whose expansion snapshot_hook runs (LaTeX’s \document).

snapshot_hook: Option<Hook>

Called once, when snapshot_cs is expanded (see snapshot).

page_hook: Option<fn(&mut Engine)>

Called after each page is shipped out, to take a page checkpoint, and once when the document has begun (see snapshot).

final_hook: Option<fn(&mut Engine)>

Called when the run is over, before the output file is finished (see snapshot).

fp_cache: Option<Box<FpCache>>

Hashes of the code-table pages and macros that existed when fingerprints were prepared (see fingerprint).

edit_request: Option<(Vec<u8>, i32)>

The file and line the user asked to edit at an error (E); the program runs the editor at the end.

output_written: Option<(String, u32, u64)>

The output file written at the end: name, pages and bytes.

input_line_for_lua: i32

The line number reported while reading Lua output.

backend_cs: HashMap<&'static str, CsId>

Internal tokens made by \pdfvariable, by variable name.

local_level: u32

Nesting depth of local control loops (tex.runtoks).

lua_scanned_box: Option<NodeRef>

The box token.scan_list scanned, once finished.

lua_scan_waiting: bool

Whether token.scan_list runs local control for its box.

backend: Option<Box<dyn Backend>>

The output backend (PDF writer), if any.

dvi: DviWriter

The DVI writer (\outputmode=0).

languages: Vec<Option<Language>>

Hyphenation languages, by \language number.

pdf: PdfState

Document-level PDF data from \pdfextension.

colorstack_values: HashMap<i32, Vec<Vec<u8>>>

Current values of the colour stacks during shipout.

total_pages: u32

Number of pages shipped out.

math_glues: Vec<Glue>

Muglue values of \Umath… spacing parameters.

math_params_initialized: bool

Whether the parameters set by the first formula are initialized (see mathparams).

synctex: Synctex

SyncTeX output.

Implementations

impl Engine

pub fn align_preamble_list(&mut self) -> NodeRef

The current alignment’s preamble as LuaTeX shows it after align_head (tex.lists.align_head): tabskip glue around an align record per column; null outside alignments.

pub fn init_align(&mut self)

Starts an alignment (init_align).

pub fn align_peek(&mut self)

Looks for \noalign, \omit or the end after \cr (align_peek).

pub fn insert_v_template(&mut self)

Inserts the v part of an alignment template (§789).

pub fn do_endv(&mut self)

\endtemplate (do_endv).

impl Engine

pub fn expand_backend_variable(&mut self)

Expands \pdfvariable name to its internal token.

pub fn expand_backend_feedback(&mut self)

Expands \pdffeedback name.

pub fn pdf_creation_date(&self) -> String

The creation date in PDF format, as \pdffeedback creationdate.

impl Engine

pub fn push_saved(&mut self, v: i64)

Pushes an auxiliary value (TeX’s saved(0):=v; incr(save_ptr)).

pub fn pop_saved(&mut self) -> i64

Pops an auxiliary value.

pub fn peek_saved(&self, k: usize) -> i64

The auxiliary value k entries below the top (saved(-1-k)).

pub fn set_peek_saved(&mut self, k: usize, v: i64)

Replaces the auxiliary value k entries below the top.

pub fn new_param_glue(&mut self, sub: u16) -> NodeRef

A glue node for glue parameter sub (new_param_glue).

pub fn new_glue_node(&mut self, spec: Glue, sub: u16) -> NodeRef

A glue node with the given specification.

pub fn new_kern_node(&mut self, w: i32, sub: u16) -> NodeRef

A kern node.

pub fn new_penalty_node(&mut self, m: i32) -> NodeRef

A penalty node.

pub fn new_null_box_node(&mut self, hlist: bool) -> NodeRef

An empty box (new_null_box) with the current attributes.

pub fn typeset_command(&mut self)

Commands that build lists and boxes (the cases of main_control not handled in crate::maincontrol).

pub fn append_glue(&mut self)

\hskip, \vskip, \hfil, … (append_glue).

pub fn append_kern(&mut self)

\kern, \mkern (append_kern).

pub fn scan_rule_spec(&mut self) -> NodeRef

Scans \hrule/\vrule dimensions (scan_rule_spec).

pub fn scan_spec(&mut self, c: GroupCode, ctx: Option<i64>)

Scans a box specification and pushes it with a new group (scan_spec); ctx is the box context to save, if any.

pub fn pop_spec_pub(&mut self) -> (PackSpec, i64)

Pops the specification pushed by scan_spec (for \vcenter).

pub fn scan_box(&mut self, ctx: BoxContext)

Scans a box and builds it in context ctx (scan_box).

pub fn begin_box(&mut self, ctx: BoxContext)

Starts building a box of the kind given by cur_chr, or fetches a box register (begin_box).

pub fn copy_node_list(&mut self, p: NodeRef) -> NodeRef

Copies a node list (copy_node_list).

pub fn box_end(&mut self, ctx: BoxContext, cur_box: NodeRef)

Does the right thing with a finished box (box_end).

pub fn start_adjust_lists(&mut self)

Starts collecting \vadjust and \insert material in hpack (TeX’s adjust_tail:=adjust_head).

pub fn set_box_register(&mut self, n: u32, global: bool, b: NodeRef)

Stores a box in a register, freeing the old contents when they are not saved for restoration.

pub fn node_height(&self, p: NodeRef) -> i32

The height of a box or rule node.

pub fn node_depth(&self, p: NodeRef) -> i32

The depth of a box or rule node.

pub fn new_local_par(&mut self) -> NodeRef

Makes a local paragraph node with the current local parameters.

pub fn new_graf(&mut self, indented: bool)

Starts a paragraph (new_graf).

pub fn end_graf(&mut self)

Ends a paragraph (end_graf).

pub fn normal_paragraph(&mut self)

Resets paragraph shape parameters (normal_paragraph).

pub fn output_box_num(&self) -> i32

The box register used by the output routine (\outputbox).

pub fn par_token_before_group_end(&mut self, level: i32) -> bool

With \partokencontext at least level and a paragraph in progress, a group end that would end the paragraph directly reads the par-token first: the right brace is put back behind it and true is returned (pdfTeX’s \partokencontext: 1 for \vbox, \vtop and \vcenter; 2 also for \insert, \vadjust, \noalign and \valign items).

pub fn char_width(&self, f: u32, c: u32) -> i32

The width of character c in font f (0 if absent).

pub fn do_assignments(&mut self)

Executes assignments until a non-assignment (do_assignments).

pub fn append_boundary(&mut self)

\boundary, \noboundary, \protrusionboundary, \wordboundary.

pub fn append_to_vlist(&mut self, b: NodeRef)

Appends a box to the current vertical list with interline glue (append_to_vlist).

pub fn handle_right_brace_typesetting(&mut self)

Right braces closing box groups and other non-simple groups (cases of handle_right_brace).

impl Engine

pub fn pass_text(&mut self)

Skips text until \fi, \else or \or at level 0 (pass_text).

pub fn pop_cond(&mut self)

Pops the condition stack.

pub fn conditional(&mut self)

Expands a conditional (conditional, §498).

pub fn fi_or_else(&mut self)

Handles \fi, \else and \or met during expansion (§510).

pub fn has_primitive_meaning(&self, cs: CsId) -> bool

Whether cs currently has the meaning of the primitive of the same name (\ifprimitive).

impl Engine

pub fn watch_definitions(&mut self, names: &[Vec<u8>])

Records the definitions of names from now on (see describe), with those of the commands a robust or document command \x stands for (\x␣, \\x, \x code).

pub fn describe(&mut self, name: &[u8]) -> Description

Describes control sequence name (without the escape character).

impl Engine

pub fn new_dir_node(&mut self, dir: i8, end: bool) -> NodeRef

A new direction node, with the current attributes (observed: tagpdf finds its marked-content attribute on them).

pub fn text_dir_assigned(&mut self, d: i32, prev: i32)

After \textdir was set to d (from prev): records it and, outside vertical mode, appends the direction nodes.

pub fn end_group_text_dirs(&mut self)

Before a simple or semi-simple group ends: ends the directions begun in it (outside vertical mode).

pub fn drop_text_dirs_above(&mut self, level: u16)

After a group ended: forgets the directions recorded in it.

pub fn default_box_dir(&self) -> i32

The direction of a box being begun in the current mode, unless the box specification gives one.

pub fn begin_box_dirs(&mut self, group: GroupCode, dir: i32)

Just after the group of a box with direction dir began: sets the direction parameters inside it and starts its own text directions.

pub fn begin_math_dirs(&mut self)

Just after a math shift group began: the direction parameters become \mathdir inside it.

pub fn reset_local_counts(&mut self, whatsits: bool)

At the start of a simple or semi-simple group: LuaTeX resets its group-local counters \nolocalwhatsits and \nolocaldirs (only visible with \tracingassigns).

pub fn end_box_dirs(&mut self)

After the group of a box ended: back to the enclosing box’s text directions.

pub fn par_text_dir(&mut self)

At the start of a paragraph (observed): \begindir for the text direction outside the recorded ones, if it is not the paragraph’s direction, then one for each recorded text direction. A direction set at the outermost level is not recorded as such: it is the one outside (\pardir TRT \textdir TRT there gives none, inside a group or a box \begindir TLT and \begindir TRT).

pub fn track_open_dirs(&self, p: NodeRef, stop: NodeRef, open: &mut Vec<i8>)

Updates open (directions begun and not ended, outermost first) with the dir nodes from p up to, not including, stop.

pub fn end_dir_nodes(&mut self, open: &[i8]) -> Option<(NodeRef, NodeRef)>

A list of \enddir nodes for open, innermost first: (head, tail).

pub fn begin_dir_nodes(&mut self, open: &[i8]) -> Option<(NodeRef, NodeRef)>

A list of \begindir nodes for open, outermost first.

impl Engine

pub fn print_glue(&mut self, d: i32, order: u8, s: Option<&str>)

Prints a glue component with its order (print_glue). LuaTeX’s orders are fi, fil, fill, filll.

pub fn print_spec(&mut self, g: &Glue, s: Option<&str>)

Prints a glue specification (print_spec).

pub fn show_eqtb(&mut self, loc: Loc)

Displays an equivalent for tracing (show_eqtb).

pub fn show_box(&mut self, p: NodeRef)

Displays a box (show_box), honouring \showboxdepth and \showboxbreadth.

pub fn show_box1(&mut self, p: NodeRef)

Displays a node list with the current limits (show_node_list).

pub fn show_save_groups(&mut self)

Shows the active groups (\showgroups, e-TeX’s show_save_groups): for each group, how it started, walking the semantic nest along.

Observed in LuaTeX: the context shown before a box is its specification’s dimension taken as a shift (\moveright10.0pt\hbox to10.0pt{; \setbox and leaders never show), and an insert group shows the line where it started as the insert number.

impl Engine

pub fn print_err(&mut self, msg: &str)

Starts an error message (print_err).

pub fn diag_capture_start(&mut self)

Starts collecting a warning message (default output mode).

pub fn source_location(&self) -> Option<(String, u32, String, usize)>

The innermost input file: name, line number, line text and the reading position in it.

pub fn diag_capture_warning(&mut self, line: Option<u32>)

Records the captured warning text as a diagnostic located at line of the current file (or its current line).

pub fn record_note(&mut self, text: &str)

Records text, written to the terminal or shown, as a note at the current place (default output mode).

pub fn print_err_bytes(&mut self, msg: &[u8])

Starts an error message given as bytes.

pub fn help(&mut self, lines: &[&'static str])

Sets the help lines for the next error (top line first).

pub fn help_owned(&mut self, lines: Vec<String>)

Sets owned help lines.

pub fn error(&mut self)

Completes an error message: prints the context and help, and interacts with the user if appropriate (error, §82).

pub fn term_input(&mut self) -> Vec<u32>

Reads a line from the terminal, echoing it to the log (term_input, §71). End of input is fatal, as in TeX.

pub fn prompt_input(&mut self, prompt: &str) -> Vec<u32>

Prints a prompt and reads a line (prompt_input).

pub fn give_err_help(&mut self)

Prints \errhelp (give_err_help).

pub fn fatal_error(&mut self, s: &str) -> !

Reports a fatal error and ends the run (fatal_error).

pub fn luatex_fatal(&mut self, category: &str, msg: &str) -> !

A LuaTeX fatal error of category category (as LuaTeX prints them: ! error: (category): message, then ! ==> Fatal error occurred, …); ends the run without the transcript line.

pub fn overflow(&mut self, s: &str, n: i64) -> !

Reports that a capacity was exceeded and ends the run (overflow).

pub fn confusion(&mut self, s: &str) -> !

Reports an internal inconsistency (confusion).

pub fn jump_out(&mut self) -> !

Ends the run (jump_out): closes files and unwinds to the driver.

pub fn normalize_selector(&mut self)

Makes sure output goes somewhere sensible (normalize_selector).

pub fn check_interrupt(&mut self)

Hook for user interrupts; retex does not support them.

pub fn back_error(&mut self)

back_error: backs up the current token and reports an error.

pub fn ins_error(&mut self)

ins_error: like back_error but the token is marked inserted.

pub fn luatex_warning(&mut self, category: &str, msg: &str)

A LuaTeX warning (warning (category): message on a line of its own); it counts as a warning for the final “see the transcript” note.

pub fn begin_diagnostic(&mut self)

Starts diagnostic output (begin_diagnostic): goes to the log only unless \tracingonline > 0.

pub fn end_diagnostic(&mut self, blank_line: bool)

Ends diagnostic output (end_diagnostic).

pub fn show_context(&mut self)

Shows where the scanner is (show_context, §311).

pub fn set_trick_count(&mut self)

TeX’s set_trick_count.

impl Engine

pub fn get_x_token(&mut self)

Gets the next token, expanding macros and other expandable commands (get_x_token).

pub fn x_token(&mut self)

Expands the current token while it is expandable (x_token).

pub fn expand(&mut self)

Expands the current (expandable) command (expand).

pub fn complain_missing_endcsname(&mut self)

Reports a missing \endcsname.

pub fn insert_relax(&mut self)

Inserts \relax after the current token (insert_relax).

pub fn macro_call(&mut self)

Calls a user macro (macro_call, §389).

pub fn runaway(&mut self)

Prints the text that has run away (runaway).

pub fn check_outer_validity(&mut self)

Checks whether an \outer macro or end of file is allowed here (check_outer_validity, §336).

impl Engine

pub fn font_expansion(&self, f: u32) -> Option<FontExpansion>

The expansion parameters of font f, if it is expandable.

pub fn ef_code(&self, f: u32, c: u32) -> i32

\efcode of character c in font f (1000 by default).

pub fn set_font_expansion( &mut self, f: u32, stretch: i32, shrink: i32, step: i32, )

\expandglyphsinfont f stretch shrink step.

impl Engine

pub fn read_file_recorded(&mut self, path: &Path) -> Option<Vec<u8>>

Reads a whole file, recording it for the pass driver.

pub fn record_probe(&mut self, name: &str, found: Option<&Path>)

Records a file lookup from Lua (kpse.find_file, which expl3 uses to test whether a file exists) for the pass driver: files of the job (relative names) are recorded with their content hash, or as absent.

pub fn record_absent_file(&mut self, name: &str)

Records that file name was looked for and not found, so that the pass driver reruns when this pass writes it (e.g. the .aux file LaTeX tests for with \filesize).

pub fn name_ok(&self, name: &str, access: Access) -> bool

Whether file name may be opened for access (kpathsea’s openin_any and openout_any); if not, kpathsea’s warning goes to the standard error stream, as with LuaTeX. Names are checked as given, before any output directory or search path applies.

pub fn find_input_file( &mut self, name: &str, fmt: FileFormat, ) -> Option<PathBuf>

Looks a TeX input file up: in the output directory first, then via kpathsea.

pub fn scan_file_name(&mut self) -> Vec<u8>

Scans a file name (scan_file_name). LuaTeX also accepts a name in braces and names in double quotes.

pub fn start_input(&mut self)

\input (start_input).

pub fn prompt_file_name(&mut self, name: &[u8], s: &str, e: &str) -> !

Asks for a file name after a lookup failure (prompt_file_name). In non-interactive modes this is fatal.

pub fn open_log_file(&mut self)

Opens the log file and prints the banner (open_log_file).

pub fn shell_escape_banner(&self) -> &'static str

The first line of the log file. The line after the banner that tells the shell escape mode (none when it is disabled).

pub fn terminal_exhausted(&mut self)

The terminal line is exhausted: in \errorstopmode/\scrollmode ask for more input (§360), otherwise stop.

pub fn open_or_close_in(&mut self)

\openin and \closein (open_or_close_in).

pub fn read_toks(&mut self, n: i32, r: CsId, j: u32) -> Vec<Token>

Reads a line from a \read stream into a token list (read_toks, §482). j is 1 for \readline (e-TeX). The result starts with the END_MATCH token, as a macro body without parameters.

pub fn pseudo_start(&mut self, text_tokens: bool)

\scantokens and \scantextokens (e-TeX pseudo_start).

pub fn file_closed_checks(&mut self)

e-TeX’s check when a file ends inside groups or conditionals.

pub fn close_files_and_terminate(&mut self)

Closes everything at the end of the run (close_files_and_terminate).

impl Engine

pub fn prepare_fingerprints(&mut self)

Hashes the code-table pages and macros that exist now, so that fingerprints taken later (in this process and the processes it forks) need not hash them again: most are the preamble’s and never change.

pub fn fingerprint(&mut self) -> (Vec<(&'static str, u64)>, u64)

The fingerprint of the state, by part (for debugging), and in all.

pub fn fingerprint_dump(&self) -> String

The registers, one per line, and the names of the control sequences defined as \count and \dimen registers: for finding why the register part of two fingerprints differs (RETEX_DEBUG_FINGERPRINT).

impl Engine

pub fn font(&self, f: u32) -> &FontInfo

The font info of font f (the null font if f is invalid).

pub fn font_exists(&self, f: i32) -> bool

Whether font id f exists.

pub fn font_id_cs(&self, f: u32) -> CsId

The identifier control sequence of font f.

pub fn quad(&self, f: u32) -> i32

\fontdimen 6 (quad) of font f.

pub fn x_height(&self, f: u32) -> i32

\fontdimen 5 (x-height) of font f.

pub fn font_has_char(&self, f: u32, c: u32) -> bool

Whether font f has character c.

pub fn font_char_dimen(&self, f: u32, c: u32, which: u32) -> i32

\fontcharwd etc.: which is 0 (wd), 1 (ht), 2 (dp), 3 (ic).

pub fn print_font_name_and_size(&mut self, f: u32)

Prints a font name, with at …pt if the size differs from the design size.

pub fn scan_font_ident(&mut self)

Scans a font identifier (scan_font_ident).

pub fn find_font_dimen(&mut self, _writing: bool) -> i32

Finds a font dimension (find_font_dimen); returns its value and records its location in font_dimen_loc for assignments. Unlike TeX82, LuaTeX extends the parameters of any font (not only the most recently loaded one) when a parameter beyond the last is read or written; only n <= 0 is an error. (LuaTeX dies on absurdly large n; retex reports those as errors too, above MAX_FONT_DIMEN.)

pub fn set_font_dimen(&mut self, loc: Option<(u32, u32)>, v: i32)

Stores a \fontdimen value found by find_font_dimen.

pub fn font_int_param(&mut self, f: u32, n: u32) -> i32

\hyphenchar, \skewchar, \ignoreligaturesinfont values.

pub fn set_font_int_param(&mut self, f: u32, n: u32, v: i32)

Sets \hyphenchar, \skewchar, \ignoreligaturesinfont.

pub fn set_font_char_code(&mut self, f: u32, n: u32, c: u32, v: i32)

Sets \lpcode, \rpcode, \efcode, \tagcode. The first three are not set for characters that the font lacks.

pub fn new_font(&mut self, global: bool)

\font\cs=name at size (new_font).

pub fn load_font(&mut self, name: &[u8], size: i32) -> Option<u32>

Loads a font through the define_font callback, or the built-in loader when no callback is set, and registers it.

pub fn register_font(&mut self, info: FontInfo) -> u32

Adds a loaded font to the font table and returns its id.

pub fn check_lua_loaded_font(&mut self, f: u32)

LuaTeX’s warning for a font from the define_font callback without characters (such as dummy.tfm, which syntonly loads).

pub fn load_tfm(&mut self, name: &[u8], size: i32) -> Option<FontInfo>

LuaTeX’s built-in TFM loader (used when no define_font callback is set, e.g. while building the LaTeX format).

pub fn load_tfm_font( &mut self, tfm_name: &[u8], size: i32, font_name: &[u8], ) -> Option<u32>

Loads TFM font tfm_name at size and registers it under the name font_name (what \fontname shows). If there is a virtual font of the same name, its local fonts are loaded too (observed in LuaTeX: right after the font, in definition order, reusing a loaded TFM font of the same name and size) and its packets are attached.

pub fn lig_kern_step(&self, f: u32, left: u32, right: u32) -> Option<LigOp>

The lig/kern instruction of font f for the pair (left, right).

pub fn base_mode_kern(&self, f: u32, left: u32, right: u32) -> Option<LigOp>

The kern between characters left and right of an OpenType font loaded in base mode: luaotfload turns its GPOS kerns into a TeX lig/kern program, which math uses between ordinary characters (text is shaped by the luaotfload replacement).

pub fn math_char(&self, f: u32, c: u32) -> Option<&MathCharInfo>

The OpenType math data of character c in font f, if any.

pub fn tfm_of(&self, f: u32) -> Option<Rc<Tfm>>

The TFM data of font f, for TeX’s ligature/kerning of TFM fonts.

pub fn letterspace_font(&mut self, global: bool)

\letterspacefont (LuaTeX).

pub fn copy_font(&mut self, global: bool)

\copyfont (LuaTeX).

impl Engine

pub fn dump_engine(&self) -> Vec<u8>

Serializes the engine state into the engine section of a format.

pub fn undump_engine(&mut self, data: &[u8]) -> Result<(), FormatError>

Restores the engine state from an engine section produced by dump_engine. The engine must be freshly created (not IniTeX).

impl Engine

pub fn main_loop_char(&mut self)

Characters in horizontal mode: appends glyph nodes for the current character and the characters that follow; on return the next non-character token is current (TeX’s main loop, goto reswitch).

pub fn app_space_main(&mut self)

A space in horizontal mode.

pub fn app_explicit_space(&mut self)

\ (explicit space).

impl Engine

pub fn cur_lang(&self) -> u32

The current language number (\language, clamped as LuaTeX does).

pub fn language_mut(&mut self, n: u32) -> &mut Language

Language n, created on first use.

pub fn language(&self, n: u32) -> Option<&Language>

Language n, if it exists.

pub fn hyph_data(&mut self, _global: bool)

Executes a hyph_data command.

impl Engine

pub fn save_image_resource(&mut self, immediate: bool)

\saveimageresource (immediate: write the image at once).

pub fn use_image_resource(&mut self)

\useimageresource: appends an image node.

pub fn is_image(&self, p: NodeRef) -> bool

Whether node p is an image.

pub fn image(&self, n: u32) -> Option<&ImageResource>

The image resource with index (object number) n.

pub fn mark_image_written(&mut self, n: u32) -> bool

Records that image n is written; true the first time.

pub fn print_image_name(&mut self, n: u32)

Prints <path> for image n, as when it is written.

pub fn image_name(&self, n: u32) -> u32

The resource number of image n (/Im<k>: the k-th image saved).

pub fn box_resource(&self, n: u32) -> Option<(&BoxResource, u32)>

The box resource with index (object number) n and its resource number (/Fm<k>: the k-th box resource saved).

pub fn box_resource_slot(&self, n: u32) -> Option<usize>

The position in Engine::box_resources of the box resource with index (object number) n.

impl Engine

pub fn save_box_resource(&mut self, immediate: bool)

\saveboxresource [attr {…}] [resources {…}] <register> (immediate: write the form at once).

pub fn use_box_resource(&mut self)

\useboxresource [width…] [height…] [depth…] n.

impl Engine

pub fn new(options: &Options, term: Box<dyn Write>) -> Engine

A fresh IniTeX engine writing to term.

pub fn install_group(&mut self, group: Group, prefix: &[u8])

Defines all primitives of group with the given name prefix.

pub fn define_primitive(&mut self, prefix: &[u8], name: &[u8]) -> bool

Defines primitive name as prefix name, unless that control sequence already has a meaning (tex.enableprimitives). Returns whether it was defined.

pub fn run(&mut self) -> Outcome

Runs a complete job: reads the first line, executes until \end or \dump, and cleans up.

pub fn store_fmt_file(&mut self)

Writes the format file (store_fmt_file, §1302).

pub fn load_format(&mut self, data: &[u8]) -> Result<(), FormatError>

Loads a format file into a freshly created (non-IniTeX) engine.

pub fn latex_release(&self) -> Option<Vec<u8>>

The release of a LaTeX format (\fmtversion when \fmtname is LaTeX2e), as YYYY-MM-DD (or YYYY/MM/DD, normalized).

LuaTeX 1.24 (TeX Live 2026) typesets math differently from 1.22 (TeX Live 2025): the italic correction of a character nucleus is always added (Engine::math_124). A format records no engine version, but its LaTeX release tells which TeX Live, hence which LuaTeX, it belongs to: LaTeX 2026-06 came with TeX Live 2026.

pub fn define_macro_str(&mut self, name: &str, body: &str)

Defines a macro from a string (for tests and bootstrapping).

impl Engine

pub fn begin_token_list(&mut self, list: TokenList, kind: TokKind)

Pushes a token list onto the input stack (begin_token_list).

pub fn begin_macro( &mut self, list: TokenList, start: usize, name: CsId, param_start: usize, )

Pushes a macro body with its parameters (already on the parameter stack starting at param_start).

pub fn ins_list(&mut self, list: TokenList)

Inserts a token list for immediate reading (ins_list).

pub fn end_token_list(&mut self)

Pops the current token-list level (end_token_list).

pub fn back_input(&mut self)

Puts the current token back into the input (back_input).

pub fn back_input_inserted(&mut self)

Backs up the current token and marks it as inserted (back_error uses this through ins_error).

pub fn begin_file_reading( &mut self, source: LineSource, name: Vec<u8>, is_input_file: bool, )

Pushes a text level reading source. Files, pseudo-files and \read streams nest at most MAX_IN_OPEN deep, as in LuaTeX.

pub fn end_file_reading(&mut self)

Pops the current text level (end_file_reading).

pub fn get_next(&mut self)

Sets cur_cmd, cur_chr and cur_cs to the next token (get_next).

pub fn catcode_in_mode(&self, c: u32, mode: CatMode) -> u8

The category code of c under a line’s catcode regime.

pub fn push_lua_output(&mut self, items: Vec<LuaItem>)

Pushes the output collected from a Lua call as a new input level.

pub fn get_token(&mut self)

Gets the next token, setting cur_tok too (get_token).

pub fn make_cur_tok(&self) -> Token

The token corresponding to cur_cmd/cur_chr/cur_cs.

impl Engine

pub fn line_break(&mut self, final_widow_penalty: i32)

Breaks the current paragraph into lines and appends them to the enclosing vertical list (line_break). widow_penalty is the penalty before the last line (\widowpenalty or \displaywidowpenalty).

pub fn par_params(&self, widow_penalty: i32, display: bool) -> ParParams

The line breaking parameters of a paragraph: the current values, with widow_penalty (\widowpenalty or \displaywidowpenalty) before the last line.

pub fn lua_line_break( &mut self, head: NodeRef, p: &ParParams, ) -> (NodeRef, LineBreakInfo)

tex.linebreak: breaks the list head (which should end with the \parfillskip glue) into lines with parameters p, and returns the vertical list of lines, with interline glue and penalties, and what the breaking found. The list is neither hyphenated nor given to callbacks; the current list’s \prevdepth starts the interline glue, and line numbers start at 1 (observed).

impl Engine

pub fn cur_list(&self) -> &ListState

The current list state.

pub fn cur_list_mut(&mut self) -> &mut ListState

The current list state, mutably.

pub fn push_nest(&mut self, mode: Mode)

Enters a new semantic level (push_nest).

pub fn pop_nest(&mut self)

Leaves a semantic level (pop_nest). The list is not freed.

pub fn tail_append(&mut self, p: NodeRef)

Appends node p to the current list (tail_append).

pub fn print_mode(&mut self, m: Mode)

Prints a mode name (print_mode).

pub fn main_control(&mut self)

The chief executive: reads and executes commands until \end or \dump (main_control).

pub fn run_local(&mut self, list: Option<TokenList>)

Executes list in a nested main loop until it is used up (LuaTeX’s local control, used by tex.runtoks). Lua output pushed before the call is read first.

pub fn push_local_marker(&mut self)

Like run_local, but the material is whatever is already on top of the input stack above the marker inserted here. Returns the depth at which the marker was placed.

pub fn scan_list(&mut self) -> NodeRef

LuaTeX’s token.scan_list: scans a box specification and returns the box (null if there was none), running the commands of an \hbox{…} or \vbox{…} in local control.

pub fn run_local_loop(&mut self)

Runs the nested main loop until the local-control marker is met.

pub fn check_double_free(&mut self)

LuaTeX’s fatal error for a node freed twice (Lua code can put a node in two lists, or link a list into a loop).

pub fn report_illegal_case(&mut self)

Reports a command that is not allowed in this mode (report_illegal_case).

pub fn you_cant(&mut self)

Prints “You can’t use … in … mode” (you_cant).

pub fn privileged(&mut self) -> bool

Whether the mode is privileged; reports an error if not (privileged).

pub fn insert_dollar_sign(&mut self)

Inserts a missing $ (insert_dollar_sign).

pub fn handle_right_brace(&mut self)

Handles a group-ending } (handle_right_brace).

pub fn off_save(&mut self)

Recovers from a mismatched group end (off_save, §1064).

pub fn final_cleanup(&mut self)

Cleans up after main_control ends (final_cleanup).

impl Engine

pub fn new_noad(&mut self, sub: u16) -> NodeRef

A new noad of the given subtype with empty fields (new_noad).

pub fn new_math_char(&mut self, fam: u32, chr: u32) -> NodeRef

A new math_char kernel.

pub fn new_sub_list(&mut self, mlist: bool, head: NodeRef) -> NodeRef

A new sub_box or sub_mlist kernel.

pub fn new_delim(&mut self, parts: (u32, u32, u32, u32)) -> NodeRef

A new delimiter node.

pub fn new_style(&mut self, s: u8) -> NodeRef

A new style node.

pub fn noad_field(&self, p: NodeRef, f: Field) -> NodeRef

The kernel in field f of noad p.

pub fn set_noad_field(&mut self, p: NodeRef, f: Field, k: NodeRef)

Replaces the kernel in field f of noad p (the old one is not freed).

pub fn init_math(&mut self)

$ in horizontal mode (init_math).

pub fn math_command(&mut self)

Commands in math mode (the mmode+… cases of main_control).

pub fn math_right_brace(&mut self)

Right braces ending math groups, \mathchoice groups and \vcenter (cases of handle_right_brace).

pub fn math_box_end(&mut self, b: NodeRef)

Appends a box in math mode as an ord noad with a sub_box nucleus (§1076).

pub fn math_char_in_text(&mut self)

Mathchars in horizontal mode: LuaTeX typesets the character in the text font of its family.

pub fn fam_fnt(&self, fam: u32, size: u32) -> u32

The font of family fam in size size (0 text, 1 script, 2 scriptscript): fam_fnt.

pub fn math_param_value(&self, p: u32, s: u32) -> i32

The value of math parameter p in style s.

pub fn finish_display_alignment( &mut self, p: NodeRef, q: NodeRef, aux_save: i32, )

Finishes an alignment in a display (§1206).

pub fn flush_math(&mut self)

Empties the current math list (flush_math).

pub fn ins_tokens(&mut self, toks: Vec<Token>)

Inserts the tokens of a list as if typed (used by error recovery).

impl Engine

pub fn print_style(&mut self, s: u32)

Prints a style (print_style).

pub fn print_fam_and_char(&mut self, p: NodeRef)

Prints family and character of a math_char kernel (print_fam_and_char).

pub fn print_delimiter(&mut self, p: NodeRef)

Prints a delimiter as a hexadecimal value (print_delimiter).

pub fn delim_fields(&self, p: NodeRef) -> (u32, u32, u32, u32)

The fields (small family, small character, large family, large character) of a delimiter node; zeros for null.

pub fn display_math_node(&mut self, p: NodeRef) -> bool

Displays a math node or noad; returns false if p is not one.

impl Engine

pub fn define_math_param(&mut self, global: bool, p: u32, s: u32, v: i32)

Defines math parameter p for style s. Assignments are traced only when \tracingassigns is 2 or more (LuaTeX manual, “Less tracing”).

pub fn set_font_math_params( &mut self, global: bool, size: u32, fam: u32, f: u32, )

Sets the math parameters that follow from assigning font f to family fam in size size (0 text, 1 script, 2 scriptscript).

pub fn set_opentype_math_params( &mut self, global: bool, size: u32, f: u32, ) -> bool

Sets the math parameters from an OpenType MATH table; returns false if font f has none.

pub fn init_math_params_once(&mut self)

Initializes the parameters LuaTeX sets when the first formula is typeset (\Umathspaceafterscript from \scriptspace).

impl Engine

pub fn print_esc_bytes(&mut self, s: &[u8])

Prints the escape character (if valid) followed by s (print_esc).

pub fn print_esc_str(&mut self, s: &str)

print_esc_bytes for ASCII names.

pub fn print_cs(&mut self, p: CsId)

Prints a control sequence with a trailing space where TeX adds one (print_cs).

pub fn sprint_cs(&mut self, p: CsId)

Prints a control sequence without a trailing space (sprint_cs).

pub fn show_token_list( &mut self, list: &[Token], start: usize, end: usize, l: i64, )

Displays tokens list[start..end], at most about l characters (show_token_list). When pseudo-printing, the position loc (if given via Engine::show_token_list_ctx) sets the trick count.

pub fn show_token_list_ctx(&mut self, list: &[Token], loc: usize, l: i64)

show_token_list for context display: the whole list is shown and the break happens at loc.

pub fn token_show_list( &mut self, list: &[Token], start: usize, end: usize, l: i64, )

token_show for a whole list.

pub fn print_cmd_chr(&mut self, cmd: Cmd, chr: u32)

Prints a symbolic form of a command and modifier (print_cmd_chr).

pub fn print_meaning(&mut self)

Prints the meaning of the current command (print_meaning).

pub fn show_cur_cmd_chr(&mut self)

Shows the current command in a diagnostic (show_cur_cmd_chr).

impl Engine

pub fn record_latex_warning(&mut self, text: &str)

Records a LaTeX/package warning written to the terminal (default output mode).

pub fn do_extension(&mut self)

Extension commands (do_extension).

pub fn append_ext_whatsit(&mut self, w: Whatsit)

Appends a whatsit node to the current list.

pub fn open_write_stream(&mut self, n: i32, name: &[u8])

Opens \write stream n on file name (.tex added if no extension).

pub fn close_write_stream(&mut self, n: i32)

Closes \write stream n.

pub fn write_out(&mut self, stream: i32, list: &TokenList)

Expands and writes a \write text (write_out).

pub fn do_normal(&mut self)

LuaTeX’s normal commands (\savecatcodetable, …).

pub fn scan_direction_spec(&mut self) -> i32

Scans a direction specifier (TLT, TRT, RTT, LTL).

pub fn assign_dir_param(&mut self, global: bool, p: u32, d: i32)

Stores a direction parameter (\textdir etc.). Observed in LuaTeX: the assignment is always local, even with \global.

pub fn dir_param(&self, p: u32) -> i32

Reads a direction parameter.

pub fn set_box_dir(&mut self, _n: u32, _d: i32)

Sets the direction of a box register.

pub fn uniform_deviate(&mut self, n: i32) -> i32

\uniformdeviate n: METAFONT’s unif_rand(n), between 0 (inclusive) and n (exclusive).

pub fn normal_deviate(&mut self) -> i32

\normaldeviate: METAFONT’s norm_rand, a scaled normal deviate.

pub fn immediate_assignment(&mut self, group: bool)

LuaTeX’s \immediateassignment / \immediateassigned.

pub fn backend_expandable(&mut self)

\pdfvariable and \pdffeedback in expansion contexts.

pub fn last_saved_resource(&self, m: u32) -> i32

The last saved box/image resource indices.

pub fn def_lua_call(&mut self, global: bool, protected: bool)

\luadef: an expandable Lua call, or a non-expandable one when \protected.

pub fn lua_code(&mut self, toks: &[Token]) -> Vec<u8>

The Lua code for the token list of \directlua or \latelua: the list as text, without control sequences named par (LuaTeX drops them, so blank lines in Lua code are harmless).

pub fn run_lua(&mut self, code: &[u8])

Runs Lua code for \directlua.

pub fn lua_error(&mut self, msg: &str)

Reports a Lua error the way LuaTeX does.

pub fn call_lua_function(&mut self, n: i32)

Calls a registered Lua function (\luafunction n).

pub fn call_lua_bytecode(&mut self, n: i32)

Calls stored Lua bytecode (\luabytecode n).

pub fn lua_expandable_call(&mut self)

Expandable Lua calls defined by \luadef.

pub fn finish_output(&mut self)

Finishes output files at the end of the run (PDF backend hook).

pub fn store_math_param_glue(&mut self, g: Glue) -> i32

Stores a muglue \Umath… parameter.

pub fn math_param_glue(&self, v: i32) -> Glue

Retrieves a muglue \Umath… parameter.

impl Engine

pub fn dimen_from_string(&mut self, s: &str) -> i64

Converts a dimension string like "1.5pt" to scaled points by running TeX’s dimension scanner on it (for the Lua API).

impl Engine

pub fn is_opentype_math_font(&self, f: u32) -> bool

Whether font f is an OpenType math font (it has MathConstants), which LuaTeX treats differently from TFM fonts.

pub fn math_spacing(&self, l: u32, r: u32, style: u32) -> Option<(Glue, u16)>

The spacing between atoms of classes l and r in style: the \Umath…spacing parameter when set (plain glue), otherwise TeX’s table with the current \thinmuskip, \medmuskip or \thickmuskip (named glue), or none.

impl Engine

pub fn noad_type(&self, q: NodeRef) -> Option<NoadType>

The TeX82 type of noad q (None for nodes).

pub fn math_par(&self, p: u32) -> i32

Math parameter p in the current style (0 when undefined).

pub fn mlist_to_hlist( &mut self, mlist: NodeRef, style: i32, penalties: bool, ) -> NodeRef

Converts mlist mlist in style style into an hlist, which is returned (mlist_to_hlist). penalties asks for line-break penalties after binary operators and relations.

pub fn math_glue(&self, g: Glue, m: i32) -> Glue

Converts mu glue to ordinary glue (math_glue).

pub fn print_size(&mut self, s: u32)

Prints \textfont, \scriptfont or \scriptscriptfont (print_size).

pub fn char_warning(&mut self, f: u32, c: u32)

Reports a missing character (char_warning) when \tracinglostchars is positive.

pub fn var_delimiter( &mut self, d: NodeRef, s: u32, v: i32, shift: bool, ) -> NodeRef

A box with the smallest variant of delimiter d whose height plus depth is at least v, built from extensible pieces if needed, centered on the axis of size s (var_delimiter). Its nodes take the attributes of the delimiter (none for a null one; observed).

impl Engine

pub fn macro_fingerprint(&self, mac: &Macro) -> u64

The fingerprint of a macro definition: FNV-1a over its tokens, control sequences by name (so it does not depend on the format or on the order in which names were created).

pub fn native_following(&self) -> Option<&[Token]>

The rest of the token list being read after the macro’s arguments, if the input comes from a token list: for implementations whose TeX code goes on to read more than its parameters (with further macros). It may contain macro-parameter tokens (out_param), which match no character or control sequence.

pub fn native_following_subst(&self) -> Option<Following>

The tokens that follow in the input, as TeX would read them, across the token lists on top of the input stack (macro parameters replaced), up to the first level that is not a token list or is a u/v template.

pub fn native_consume(&mut self, f: &Following, n: usize)

Consumes the first n tokens of a Following (which must end at the end of a token of the lists, see Following::count): ends the lists they use up, and moves on in the last one.

pub fn native_skip(&mut self, n: usize)

Consumes the first n tokens of native_following, which must hold balanced braces and no macro-parameter tokens: reading them would have no other effect.

pub fn native_insert(&mut self, tokens: Vec<Token>)

Puts tokens back into the input, to be read next (what an expandable macro’s result does).

impl Engine

pub fn lang_params(&self, l: u32) -> Settings

The hyphenation parameters of language l.

pub fn new_char_node(&mut self, f: u32, c: u32) -> NodeRef

A new glyph node in font f with the current language data (LuaTeX’s new_char).

pub fn node_process_list(&mut self, first: NodeRef, ctx: Context) -> NodeRef

Runs the hyphenation, ligaturing and kerning passes over the list starting at first; returns the new first node.

pub fn lua_node_pass( &mut self, pass: NodePass, head: NodeRef, ) -> (NodeRef, NodeRef)

Runs one built-in pass (node.ligaturing, node.kerning, lang.hyphenate) over the list head, which may start with a temporary node (as in the callbacks); returns the new head and the tail.

impl Engine

pub fn check_lost_char(&mut self, p: NodeRef)

With \tracinglostchars 4 or more (LaTeX’s setting), reports glyph p if its font lacks its character, as LuaTeX does each time it measures the glyph (when packing a box and in each line-breaking pass): Missing character: There is no ペ (U+30DA) in font cmr10! on its own line, whatever \tracingonline (observed).

pub fn shipout_lost_char(&mut self, f: u32, c: u32)

Reports character c of font f, which the font lacks, when it is shipped out (observed): with \tracinglostchars 1 in the log only (unless \tracingonline), from 2 on the terminal too, and with 3 as an error (context, no help).

pub fn glyph_dimensions(&self, p: NodeRef) -> (i32, i32, i32)

The dimensions (width, height, depth) of a glyph node. Observed: the yoffset raises or lowers the height, but only a raised glyph has a smaller depth; a lowered one keeps its depth.

pub fn hpack(&mut self, p: NodeRef, spec: PackSpec) -> NodeRef

Packs the hlist p into an hbox (hpack).

pub fn natural_dimensions(&self, p: NodeRef, stop: NodeRef) -> (i32, i32, i32)

The natural width, height and depth of the hlist from p up to stop (exclusive), as hpack measures it (LuaTeX’s node.dimensions).

pub fn vpack(&mut self, p: NodeRef, spec: PackSpec) -> NodeRef

Packs a vlist with unlimited depth (vpack).

pub fn vpackage(&mut self, p: NodeRef, spec: PackSpec, l: i32) -> NodeRef

Packs the vlist p into a vbox with maximum depth l (vpackage).

impl Engine

pub fn prune_page_top(&mut self, p: NodeRef, save: bool) -> NodeRef

Removes glue, kerns and penalties before the first box or rule and inserts \splittopskip glue (prune_page_top). With save, the removed items go to \splitdiscards.

pub fn vert_break(&mut self, p: NodeRef, h: i32, d: i32) -> (NodeRef, i32)

Finds the best place to break a vlist for height h and maximum depth d (vert_break); returns the break node (null for the end) and best_height_plus_depth.

pub fn vsplit(&mut self, n: u32, h: i32) -> NodeRef

\vsplit n to h (vsplit).

pub fn build_page(&mut self)

Appends contributions to the current page (build_page).

pub fn resume_output(&mut self)

Resumes the page builder after the output routine (§1026).

impl Engine

pub fn underfull_page_note( &self, badness: i32, ) -> Option<(String, Vec<String>, Vec<String>)>

The message and help lines for an underfull page, from the last page break. Returns the message, the notes (causes) and the help (suggestions).

impl Engine

pub fn pdf_alloc_obj(&mut self, kind: ObjKind) -> i32

Allocates a PDF object number of kind kind.

pub fn pdf_obj_kind(&self, n: i32) -> Option<ObjKind>

The kind of object number n, if it was allocated.

pub fn pdf_page_ref(&mut self, page: i32) -> i32

The object number of page page (counting from 1), allocated on first request (pdf.getpageref, \pdffeedback pageref).

pub fn pdf_dest_obj(&mut self, id: &DestId) -> i32

The object number of destination id, allocated on first use.

pub fn pdf_struct_dest_obj(&mut self, id: &DestId) -> i32

The object number of structure destination id, allocated on first use.

pub fn pdf_font(&mut self, f: u32) -> (u32, i32)

The PDF font of font f: the number in its resource name /F<n> and its object number. Fonts with the same name share one PDF font. It is created when first asked for (by \pdffeedback fontname or fontobjnum, or their Lua counterparts), named after the font asked for, and gets an object number then (observed: asking for cmr10 at 12pt before cmr10 names both after the former).

pub fn pdf_ensure_colorstacks(&mut self)

Makes sure the predefined colour stack 0 exists.

pub fn pdf_new_colorstack(&mut self, init: Vec<u8>, page: bool, mode: u8) -> i32

Defines a new colour stack and returns its number; stack 0 is the predefined one (\pdffeedback colorstackinit, pdf.newcolorstack).

pub fn pdf_append_refobj(&mut self, n: i32)

Appends a pdf_refobj whatsit for object n to the current list (\pdfextension refobj, pdf.refobj in \directlua).

pub fn pdf_define_object(&mut self, obj: PdfObject, immediate: bool)

Stores object obj, makes it \pdffeedback lastobj, and writes it now if immediate.

Observed: LuaTeX’s “words of extra memory” grow by 5 for each object from \pdfextension obj (immediate or not) and from pdf.obj, but not from pdf.immediateobj or a reservation.

pub fn pdf_fatal(&mut self, msg: &str) -> !

Reports a fatal backend error the way LuaTeX does and ends the run without writing the PDF file.

pub fn pdf_fatal_in(&mut self, category: &str, msg: &str) -> !

Engine::pdf_fatal with another category.

pub fn pdf_warning(&mut self, msg: &str)

Prints a backend warning on a line of its own (warning (pdf backend): …).

pub fn pdf_action_text(&mut self, action: &PdfAction) -> Vec<u8>

The PDF text of an action (a dictionary, or the user text), allocating the objects of the destinations, pages and threads it refers to.

pub fn pdf_extension(&mut self, immediate: bool)

Executes \pdfextension (immediate when prefixed by \immediate).

pub fn pdf_write_object(&mut self, n: i32)

Writes object n through the backend now.

pub fn whatsit_tokens(list: &TokenList) -> LateData

A token list of whatsit data, for late expansion.

pub fn pdf_finish_document(&mut self)

Works out what the backend needs at the end of the run, and prints LuaTeX’s warnings about destinations and threads that were referred to but never defined.

impl Engine

pub fn get_r_token(&mut self)

Gets a redefinable control sequence (get_r_token).

pub fn prefixed_command(&mut self)

Performs an assignment, possibly prefixed (prefixed_command).

pub fn int_param_changed(&mut self, i: u32)

Hooks for integer parameters with side effects (\newlinechar, …).

pub fn new_interaction(&mut self)

\batchmode etc. (new_interaction).

impl Engine

pub fn record_origins(&mut self)

Turns on the recording of where macros are defined.

pub fn start_profile(&mut self)

Starts profiling (and recording origins).

pub fn profile_tick(&mut self)

Charges the time elapsed since the last sample, if any, to the current state. Called often: cheap when there is nothing to do.

pub fn work_begin(&mut self, w: Work)

Marks the beginning of engine work w.

pub fn work_end(&mut self)

Marks the end of the innermost engine work.

pub fn origin_here(&mut self) -> u32

The origin of a definition made now: the innermost file being read and its line (0 without Origins or outside files).

pub fn finish_profile(&mut self) -> Option<Summary>

Stops the profiler and returns what it found.

impl Engine

pub fn char_protrusion(&self, p: NodeRef, left: bool) -> i32

The protrusion of glyph p into the left (left) or right margin, in sp: the \lpcode/\rpcode of its character in thousandths of the font’s quad. The margin kern is minus this amount.

pub fn margin_kern(&mut self, n: u32, left: bool) -> Option<i32>

\leftmarginkern n, \rightmarginkern n: the width of the margin kern at the start (end) of hbox n, passing over glue and penalties; None if there is none (expands to 0pt). A void box or a vbox is a fatal error in LuaTeX.

pub fn strip_margin_kerns(&mut self, head: NodeRef) -> NodeRef

Removes the margin kerns from the top level of the list p (unboxing an hbox drops them, as in LuaTeX); returns the new head.

impl Engine

pub fn new_save_level(&mut self, c: GroupCode)

Begins a new group (new_save_level).

pub fn eq_define(&mut self, loc: Loc, val: Val)

Defines loc locally (eq_define / eq_word_define).

pub fn define_codes_identity(&mut self, kind: CodeKind, upto: u32)

Local \lccode c = c (or the like for kind) for every c < upto, with the save-stack effect of the individual assignments: for natives. Only inside a group (above level one), with no \globaldefs and no tracing, before any other assignment to the table in this group.

pub fn geq_define(&mut self, loc: Loc, val: Val)

Defines loc globally (geq_define / geq_word_define).

pub fn define(&mut self, global: bool, loc: Loc, val: Val)

Defines loc locally or globally.

pub fn save_for_after(&mut self, t: Token)

Saves a token for insertion at the end of the group (save_for_after).

pub fn unsave(&mut self)

Ends the current group (unsave).

pub fn group_line(&self) -> i32

The line number saved with the current group boundary.

pub fn print_group(&mut self, e: bool)

Prints a description of the current group (print_group).

pub fn restore_trace(&mut self, loc: Loc, s: &str)

Traces an assignment or restoration (restore_trace). Observed: LuaTeX does not trace its character code tables (\catcode, \lccode, \uccode, \sfcode, \mathcode, \delcode).

impl Engine

pub fn get_nonblank_noncall(&mut self)

Gets the next non-blank non-call token (TeX §406).

pub fn get_nonblank_or_protected(&mut self)

Gets the next non-blank token, expanding everything except protected macros (e-TeX’s get_x_or_protected loop, used where an alignment looks for \noalign or \omit).

pub fn get_nonblank_nonrelax_noncall(&mut self)

Gets the next non-blank non-relax non-call token (§404).

pub fn scan_optional_space(&mut self)

Scans an optional space (§443).

pub fn scan_left_brace(&mut self)

Scans a left brace, inserting one if missing (scan_left_brace).

pub fn scan_optional_equals(&mut self)

Scans an optional = (scan_optional_equals).

pub fn scan_keyword(&mut self, s: &str) -> bool

Looks for a keyword (scan_keyword); letters match either case.

pub fn back_list(&mut self, list: TokenList)

Pushes a token list to be read again (back_list).

pub fn mu_error(&mut self)

Reports an inappropriate mu/non-mu mix (mu_error).

pub fn scan_int(&mut self)

Scans a signed integer into cur_val (scan_int).

pub fn scan_register_num(&mut self)

Scans a register number 0–65535 (LuaTeX’s scan_register_num).

pub fn scan_char_num(&mut self)

Scans a character code 0–0x10FFFF (scan_char_num).

pub fn scan_four_bit_int(&mut self)

Scans a stream number for \read, \openin, \ifeof (0–15).

pub fn scan_four_bit_int_or_more(&mut self)

Scans a stream number for \ifeof and \read; LuaTeX accepts any integer here and treats out-of-range streams as closed.

pub fn scan_math_given(&mut self) -> u32

Scans a math character for \mathchardef, \mathchar and \mathaccent (scan_fifteen_bit_int) and returns it as a math_given value; cur_val is the number \the reports.

Observed in LuaTeX 1.22: numbers above "8000 (math active) are read as packed math codes (class·2²¹ + family·2²⁴ + character, what \mathcode reports for \Umathcodes), so \mathchardef\x\mathcodec` works; a character beyond U+10FFFF is an “Invalid math code during > 0x8000 mathcode fallback”, a negative number a “Bad mathchar”.

pub fn scan_twenty_seven_bit_int(&mut self)

Scans a 27-bit delimiter code (scan_twenty_seven_bit_int).

pub fn scan_math_family(&mut self)

Scans a math family number 0–255 (LuaTeX).

pub fn scan_category_code(&mut self)

Scans a category code 0–15.

pub fn scan_normal_dimen(&mut self)

Scans a normal dimension (scan_normal_dimen).

pub fn scan_dimen(&mut self, mu: bool, inf: bool, shortcut: bool) -> GlueOrder

Scans a dimension (scan_dimen, §448). mu: units must be mu; inf: infinite units allowed; shortcut: cur_val already holds the integer part. Sets cur_val, and cur_order via the returned order.

pub fn prepare_mag(&mut self)

Freezes the magnification (prepare_mag).

pub fn int_error(&mut self, n: i32)

Reports an error with an integer in parentheses (int_error).

pub fn scan_glue(&mut self, level: ValLevel)

Scans glue (scan_glue); level is ValLevel::Glue or ValLevel::Mu. Sets cur_glue.

pub fn scan_something_internal(&mut self, level: ValLevel, negative: bool)

Fetches an internal quantity (scan_something_internal, §413).

pub fn scan_normal_glue(&mut self)

Scans glue (scan_normal_glue).

pub fn scan_mu_glue(&mut self)

Scans muglue (scan_mu_glue).

pub fn scan_math_style(&mut self) -> bool

Scans the math style of a \Umath… parameter: a style command (\displaystyle, \crampedtextstyle, …), whose number (0–7) is left in cur_val. Anything else is put back and reported, and \displaystyle is used (as LuaTeX 1.22 does; numbers are not accepted). Returns whether a style was found.

pub fn scan_expr(&mut self, level: ValLevel)

Evaluates an e-TeX expression (scan_expr). Sets cur_val (or cur_glue) and cur_val_level.

pub fn scan_toks(&mut self, macro_def: bool, xpand: bool) -> Vec<Token>

Scans a balanced text (scan_toks). For macro definitions (macro_def), the parameter text is scanned first and the result contains match tokens, END_MATCH and the body. With xpand, the text is expanded as in \edef. Returns the list and whether the definition text used # correctly.

impl Engine

pub fn ship_out(&mut self, p: NodeRef)

Ships box p out (ship_out).

pub fn finish_pdf_only(&mut self) -> bool

Finishes the PDF file and nothing else, quietly: for --watch, in a process that writes a PDF spliced from two runs (see Backend::splice). Returns whether it was written.

pub fn vf_command(&mut self, cmd: &PacketCommand) -> bool

Runs cmd in the packet whose lua command is running (the vf library); false outside one.

pub fn vf_scaled(&mut self, x: i64) -> Option<i32>

A dimension given to the vf library (vf.right(x)) in the packet whose lua command is running: observed, x is a fix_word scaled by the size of the virtual font, as dimensions in VF files are, and one beyond 16 times the size is a fatal error. None outside a packet.

pub fn write_box_resource( &mut self, be: Box<dyn Backend>, n: u32, ) -> Box<dyn Backend>

Writes box resource n as a form: ships its box into the form with the box’s reference point at (0, depth), then the forms it uses that are not written yet, then its resources.

pub fn finish_backend(&mut self)

Finishes the output file at the end of the run and reports it.

impl Engine

pub fn print_font_id(&mut self, f: u32)

Prints the identifier of font f (\tenrm).

pub fn print_font_and_char(&mut self, p: NodeRef)

Prints a glyph as \font c (print_font_and_char).

pub fn short_display(&mut self, p: NodeRef)

Prints the highlights of list p (short_display).

pub fn show_node_list(&mut self, p: NodeRef)

Displays a node list (show_node_list).

pub fn display_node_list(&mut self, p: NodeRef)

Kept for callers of the old name.

pub fn print_skip_param(&mut self, sub: u16)

Prints the name of a glue parameter given a glue subtype (print_skip_param).

pub fn show_activities(&mut self)

Displays the semantic nest (show_activities).

pub fn show_page_contents(&mut self)

Shows the current page in \showlists (§986).

pub fn print_totals(&mut self)

Prints the page totals (print_totals).

pub fn show_box_param_limits(&mut self)

The \tracingonline-dependent part of box display used by \showbox (show_box).

impl Engine

pub fn snapshot_outputs(&mut self) -> Vec<OpenOutput>

Flushes all output and lists the output files that are open.

pub fn outputs_intact(&self, outputs: &[OpenOutput]) -> bool

Whether the output files listed by snapshot_outputs are still there, at least as long as at the snapshot, so that a pass can resume from it: a failed build may have removed one (the PDF file of a build that shipped no page).

pub fn resume_outputs(&mut self, outputs: &[OpenOutput]) -> Result<()>

In a process resumed from a snapshot: reopens the output files listed by snapshot_outputs, truncated to their length at the snapshot.

pub fn open_input_files(&self) -> Vec<PathBuf>

The input files being read, from the outermost.

pub fn reloaded_inputs(&self) -> Result<Reload, PathBuf>

Reads the input files being read again, for a process resumed from a snapshot after they were edited (--watch): the part already read must be unchanged; the rest may differ. Returns the first file whose read part changed (or that cannot be read) as the error.

pub fn reload_inputs(&mut self, reload: Reload)

Continues reading the input files with the contents of reload.

impl Engine

pub fn synctex_changed(&mut self)

Called when the job starts and when \synctex changes: starts keeping the fields of nodes once \synctex is nonzero.

impl Engine

pub fn print_to_string(&mut self, f: impl FnOnce(&mut Engine)) -> Vec<u8>

Runs f with output going to a new string and returns the string.

pub fn scan_general_text(&mut self) -> TokenList

Scans a general text {…} without expansion (e-TeX scan_general_text).

pub fn the_toks(&mut self) -> Vec<Token>

The token list for \the and friends (the_toks).

pub fn ins_the_toks(&mut self)

Inserts the result of \the into the input (ins_the_toks).

pub fn conv_toks(&mut self)

Performs a conversion command (conv_toks).

pub fn scan_toks_expanded(&mut self) -> Vec<Token>

Scans a general text with expansion as \edef does, without the enclosing braces.

pub fn cs_print_name(&self, cs: CsId) -> Vec<u8>

The name of a control sequence as \csstring prints it.

pub fn show_whatever(&mut self)

Implements \show, \showbox, \showthe, \showlists, \showgroups, \showtokens, \showifs (show_whatever).

impl Engine

pub fn filter_list(&mut self, cb: &str, head: NodeRef, group: &str) -> NodeRef

Runs the node-list filter callback cb (LuaTeX’s pre_linebreak_filter, hpack_filter, …) on the list starting at head; returns the new first node. A callback returning false discards the list.

pub fn page_is_empty(&self) -> bool

Whether the current page and contributions are empty.

pub fn not_implemented(&mut self, what: &str)

Reports a command that is not implemented yet.

pub fn cur_attr(&mut self) -> Option<AttrList>

The current attribute list (current_attribute_list).

pub fn new_node(&mut self, id: u8, subtype: u16, data: NodeData) -> NodeRef

Allocates a node carrying the current attributes.

pub fn give_new_attr(&mut self, p: NodeRef)

Gives new node p the current attributes, or those of the noad mlist_to_hlist is building nodes for.

pub fn alter_aux(&mut self)

\spacefactor, \prevdepth (alter_aux).

pub fn alter_prev_graf(&mut self)

\prevgraf (alter_prev_graf).

pub fn alter_page_so_far(&mut self)

\pagegoal etc. (alter_page_so_far).

pub fn alter_box_dimen(&mut self)

\deadcycles, \insertpenalties assignments (alter_integer) are in the prefixed-command code; \wd, \ht, \dp assignments (alter_box_dimen).

pub fn fetch_aux(&mut self, m: u32) -> Option<(i32, ValLevel)>

\spacefactor/\prevdepth values for \the.

pub fn fetch_prev_graf(&mut self) -> i32

\prevgraf value.

pub fn page_so_far_value(&self, m: u32) -> i32

\pagegoal etc. values.

pub fn fetch_last_node_item(&mut self, m: u32) -> (i32, Glue, ValLevel)

\lastpenalty, \lastkern, \lastskip, \lastnodetype (§424).

pub fn box_is_hlist(&self, p: NodeRef) -> bool

Whether box p is an hlist.

pub fn cur_math_style(&self) -> i32

Current math style (\mathstyle), or −1 outside math.

pub fn insert_height(&self, n: u32) -> i32

\insertht: the height of insertion class n on the current page.

impl Engine

pub fn has_callback(&self, name: &str) -> bool

Whether the Lua callback name is set.

pub fn notify_callback(&mut self, name: &str, info: &str)

Calls the notification callback name (buildpage_filter, contribute_filter) with info, if one is set.

pub fn build_page_from(&mut self, info: &str)

Calls buildpage_filter with info (where the page builder was called from, observed), then builds the page.

pub fn run_list_filter( &mut self, callback: &str, head: NodeRef, group: &str, ) -> ListFilter

Runs a node-list filter callback if one is registered (the hook typesetting code calls at LuaTeX’s callback points).

impl Engine

pub fn formula_to_hlist( &mut self, head: NodeRef, style: i32, penalties: bool, ) -> NodeRef

Converts a finished formula’s math list into an hlist, through the mlist_to_hlist callback when one is set (LuaTeX calls it for the outermost list of each formula and equation number; observed: not for an empty one).

pub fn print_input_level(&mut self) -> bool

Prints the input level before a line of macro tracing through the input_level_string callback (LaTeX’s \tracingstacklevels); returns false if no callback is set. A newline in the string ends the line.

pub fn run_glyph_info(&mut self, p: NodeRef) -> Option<Option<Vec<u8>>>

Runs the glyph_info callback for glyph p when one is set: None without a callback, Some(None) when it returned no string.

Trait Implementations

impl Debug for Engine

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.