Module state 

A global, singleton, mutable state - hosts almost all TeX-facing runtime information for the conversion

Re-exports

pub use crate::common::store::Stored;

pub use crate::common::local_assignments::*;

Structs

State

The state efficiently bookkeeps the bindings in a TeX-like fashion.

StateOptions

state fields allowed for customization during construction

UndoFrame

For each of several tables (being “value”, “meaning”, “catcode” or other space of names), each table maintains the bound values, and “undo” defines the stack frames

Enums

Catcodes

High-level catcode profiles

Scope

installation scope in the state_tables

TableName

the kinds of tables bookkept in the State

Statics

UNITS

Used in conversion to scaled points.

Functions

activate_scope

Activates all stashed definitions for the named scope. No-op if the scope is already active.

add_binding_names

Append one crate’s (name, ext) slice. Companion to set_bindings_dispatch / set_extra_bindings_dispatch — call alongside dispatcher registration so find_file can resolve compile-time bindings. Duplicates are deduplicated by pointer so repeated calls from the same crate don’t inflate the fallback pool.

add_search_path

Global append (Perl PushValue(SEARCHPATHS)) — a persistent search dir.

after_assignment

run the accumulated directives from \afterassignment

assign_alignment

assign_catcode

assigns a Catcode for a given character

assign_delcode

like assign_catcode but targets Delcode and its table

assign_font

a convenience method to globally asign a Font to the “font” key

assign_internal

assigns a Stored value at the given key and scope Direct mirror of Perl’s free-function form LaTeXML::Core::State::assign_internal($STATE, $table, $key, $value, $scope) (Core/State.pm L140). Bypasses every dialect / lock / let-chase / admission layer Rust has accreted on top of the table mutation; used by the dump loader (Core/Dumper.pm V/Cc/Mc/Sc/Lc/Uc/Dc/Im/I/Lt) so the dump replay matches Perl exactly: one record == one assign_internal call.

assign_lccode

like assign_catcode but targets Lccode and its table

assign_mapping

Bind key to value inside the named mapping — Perl’s AssignMapping.

assign_mathcode

like assign_catcode but targets Mathcode and its table

assign_meaning

$meaning should be a definition (for defining active control sequences) or another token, for \let

assign_register

assign_register_token

assign_register variant taking a pre-built Token — lets hot callers skip the T_CS!(&str) pin when they already have the CS cached (e.g. via T_CS!("\\c@…") literal which routes through pin!).

assign_sfcode

like assign_catcode but targets Sfcode and its table

assign_uccode

like assign_catcode but targets Uccode and its table

assign_value

Bind key to value in the value table — Perl’s AssignValue.

assign_value_inplace

assigns a Stored value ‘inplace’: replaces the front value in whatever frame it was originally assigned in, without recording an undo entry. This matches Perl’s assignValue(key, value, 'inplace'). Used for MODE changes in enter_horizontal (switches mode without creating a new binding).

assign_value_inplace_sym

Sym-keyed variant of assign_value_inplace — skip the per-call arena::pin(key) for hot callers with a pre-pinned SymStr.

assign_value_sym

assigns a Stored value at the given (arena ticket!) key and scope

begin_semiverbatim

begins a semiverbatim frame, neutralizing the usual + requested characters

binding_exists

true when a binding is registered for the exact (name, ext) pair. Convenience wrapper over the per-crate slices in binding_names. Mirrors dispatch()’s lookup but without the side effect of loading.

checkin_value

Returns a value into its Stored::None placeholder (see checkout_value for taking it)

checkout_value

Replaces the value in question with Stored::None (see checkin_value for returning it)

clear_prefixes

clears the global prefixes

compute_indirect_model

The indirect model includes all elements allowed as direct children, and all descendents of a node that can be inserted after autoOpen’ing intermediate elements.

convert_unit

convert a unit name into a f64 scaling factor over sp

convert_unit_ratio

Convert a unit name into the exact TeX (num, den) fraction such that a dimension of value units is floor(round(value·65536)·num/den) scaled points (see numeric_ops::fixpoint_unit).

current_frame_locked

true when the CURRENT (front) stack frame is the locked bottom frame — i.e. there is no openable group/mode frame to pop. Popping it would FATAL.

current_verbosity

deactivate_scope

Removes any definitions that were associated with the named scope. Normally not needed, since a scopes definitions are locally bound anyway.

diff_snapshot

Compute diff from snapshot and return changed serializable entries.

dump_top_frame_keys

Starts a new level of grouping. Note that this is lower level than C<\bgroup>; Diagnostic helper: dump the keys in undo0’s value table. For temporary instrumentation only — no production callers should rely on this.

end_semiverbatim

end by just calling pop_frame

ensure_tag_property

generate_error_stub

Generate a stub definition for an undefined control-sequence, along with appropriate error messge.

generate_ligature_id

simple id generator for a ligature

get_active_scopes

return the currently activated named scopes

get_binding_names

Snapshot of all registered (name, ext) binding pairs across all dispatchers. Used by find_file(notex=true) to detect compiled-binding existence regardless of extension (cls/sty/def/pool/code.tex/…).

get_bindings_dispatch

get_class_binding_names

Filtered view of get_binding_names() returning ONLY class names (without .cls suffix). Used by load_class for Perl’s prefix-match fallback (Package.pm L2702-2706). Returns a flat Vec<&str> rather than per-crate slices — callers that need to preserve crate boundaries should iterate get_binding_names() directly.

get_extra_bindings_dispatch

get_frame_depth

Determine depth of group nesting.

get_graphics_paths

Mirror Perl’s LookupValue('GRAPHICSPATHS') — a list value that all \graphicspath, \svgpath, initial source-directory prepends, and image_candidates consult. Always return as Vec<String> even if the value was stored as Strings (initial assignValue) or VecDequeStored (after any push/unshift).

get_indirect_model_relationship

get_input_encoding

get_known_scopes

return all known named scopes

get_label_mapping_hook

get_nomathparse_flag

get_prefix

gets the current value of a named prefix

get_prefix_sym

get_prefix with a pre-pinned SymStr key (see crate::pin!) — for the per-\def prefix probes in Expandable::new and friends.

get_search_paths

Read SEARCHPATHS from the group-scoped value table (Perl LookupValue('SEARCHPATHS')). Mirrors get_graphics_paths: the list is a group-scoped value, not a plain field, so an \import/\subimport group reverts its change at } and a package’s global add persists.

get_staged_snapshot

Retrieve a previously staged snapshot, if present.

get_tag_property

graphics_paths_contains

Zero-alloc membership test for GRAPHICSPATHS. Mirrors the Perl idiom grep { $_ eq $dir } @{ $state->lookupValue('GRAPHICSPATHS') } but without allocating an owned Vec<String> for a single boolean — the interned-symbol with/with2 family resolves each path in place.

graphics_paths_push_front

Mirror Perl’s $state->unshiftValue(GRAPHICSPATHS => $dir). Used by Core.pm-style source-directory prepends.

has_indirect_model

has_meaning

has_search_paths

has_value

Check if the Value table contains a given key

hoist_top_frame_meaning_delta

Hoist every Meaning binding installed at the topmost frame since pre_snapshot was taken to GLOBAL scope. Idempotent: keys already in pre_snapshot are skipped. Operates on the Meaning table only — callers that need to promote Value/Catcode/etc. should add parallel helpers (none required so far).

install_definition

A shorthand for installing definitions

install_undefined_error_constructor

Install a Constructor for token whose sole effect at digestion time is to emit <ltx:ERROR class='undefined'>content</ltx:ERROR> (the Rust equivalent of Perl Document::makeError). It logs NOTHING — the caller is responsible for the Error!/note_status. Mirrors the make_error constructor that generate_error_stub installs for undefined commands, so undefined environments (\begin{undefinedenv}) leave the same visible <ltx:ERROR> marker as Perl instead of silently vanishing from the output.

is_binding_extension

true when at least one registered binding declares ext as its extension. Used by \input’s heuristic to decide whether \input{name.<ext>} should consult the binding registry — e.g. .sty, .cls, .def, .pool, code.tex are all valid binding extensions, while .eps, .png, .bib are not. Matches by extension only (the name is checked separately by dispatch()’s exact lookup).

is_dont_expandable

Whether token is affected by \noexpand

is_scope_active

Is the named scope currently active? See scope_active_in for why this is a front-value test and not a presence test, and subfile_scope_at_depth for the region marker it supports.

is_serializable

Check whether a Stored value can be serialized for the kernel dump. Values containing closures (Primitive, Constructor, Conditional, etc.) cannot be serialized — they come from Rust engine code, not the dump. This matches Perl’s DumpFile which only serializes Expandable macros.

is_value_bound

Was name bound? If frame is given, check only whether it is bound in that frame (0 is the topmost).

let_i

Let macro setter

lookup_alignment

lookup_bool

A bit of Perl “existence as truth” semantics mixed in with proper boolean lookup

lookup_bool_sym

lookup_bool variant for hot call sites with a pre-pinned SymStr (see crate::pin!). Skips the per-call arena::pin(key) hash lookup — significant on every-expansion hot paths. SymStr is a u32 wrapper (Copy), so it passes by value — no borrow overhead.

lookup_catcode

Lookup & assign a character’s Catcode

lookup_conditional

lookup_definition

used for expansion & various queries Since we’re not doing digestion here, we don’t need to handle mathactive, nor cs let to executable tokens This returns a definition object, or undef

lookup_definition_stored

Returns a definition as Stored so that one can call .read_arguments

lookup_delcode

like lookup_catcode but targets Delcode and its table

lookup_digestable_definition

Recognizes mathactive tokens in math mode and also looks for cs that have been let to other `executable’ tokens. Returns a definition object, or a “self inserting” token. Used for digestion.

lookup_dimension

a variant of lookup_value that casts the value into Dimension

lookup_dimension_cs

Faithful port of Perl LookupDimension (Package.pm L1371-1393, as widened by upstream PR #2829): try to turn the argument into a Dimension, recognizing strings, registers, ….

lookup_expandable

lookup_float

a variant of lookup_value that casts the value into Float

lookup_font

convenience method to lookup the current value at the “font” key

lookup_glue

a variant of lookup_value that only recognizes a Stored::Glue

lookup_int

like lookup_value but only recognizes Int, Bool and Number variants of Stored (default: 0)

lookup_int_sym

lookup_int variant for hot call sites with a pre-pinned SymStr (see crate::pin!). Skips the per-call arena::pin(key) hash lookup — the sibling of lookup_bool_sym, added for the per-conditional if_count/if_limit probes (Conditional::invoke fires on every \if/\ifx/\ifnum/…).

lookup_lccode

like lookup_catcode but targets Lccode and its table

lookup_mapping

lookup_mapping_sym

Sym-keyed variant — skip the per-call arena::pin(map) for hot callers with a pre-pinned map key (e.g. via pin!("siunitx_macros")).

lookup_mathcode

like lookup_catcode but targets Mathcode and its table

lookup_mathcode_sym

lookup_mathfont

convenience method to lookup the current value at the “mathfont” key

lookup_meaning

Get the “Meaning” of a token.

lookup_muglue

a variant of lookup_value that only recognizes a Stored::Glue

lookup_number

a variant of lookup_value that casts the value into Number

lookup_register

lookup_register_definition

A specialized version of lookup_definition for registers, since we can’t adequately perform multi-dispatch when we have a “Self: Sized” for the Definition trait object.

lookup_register_quiet

Quiet sibling of lookup_register for call sites that mirror Perl’s explicit lookupDefinition(cs) && $defn->isRegister ? $defn->valueOf : <default> guard — e.g. TeX_Tables \lx@text@intercol/\lx@math@intercol (TeX_Tables.pool.ltxml L639/L646), where a document may legitimately \renewcommand a length register (\tabcolsep/\arraycolsep) into a plain macro. In that case the register-ness is genuinely gone in Perl too, and Perl silently falls back to its default (Dimension(0)) with no warning. Returns None (no warning) when the CS is undefined or is not a register, so the caller can apply its own faithful default.

lookup_register_token

Token-keyed variant of lookup_register — saves the per-call T_CS!(&str) pin for hot callers with a cached CS token.

lookup_sfcode

like lookup_catcode but targets Sfcode and its table

lookup_string

like lookup_value, but casts the entry into a String (empty if None)

lookup_string_from_sym

lookup_string variant using a pre-pinned SymStr key.

lookup_string_sym

like lookup_value, but casts the entry into a SymStr from the string interner (pin!("") if None)

lookup_token

a variant of lookup_value that only recognizes a Stored::Token

lookup_token_sym

a variant of lookup_token taking an already-pinned SymStr key — avoids the per-call arena::pin(key) hash lookup.

lookup_tokens

a variant of lookup_value that casts the response into Tokens

lookup_uccode

like lookup_catcode but targets Uccode and its table

lookup_value

The value bound to key, or None when nothing is bound — Perl’s LookupValue.

lookup_vecdeque

like lookup_value but only recognizes Stored::VecDequeStored

meaning_key

The key under which a token’s meaning is stored. All \special_relax-family tokens (\noexpand’d forms — the bare \special_relax and every \special_relax\x01<shadowed>) resolve under the bare \special_relax name: they share its \relax meaning, faithful to TeX where a \noexpand’d token has relax meaning regardless of which token it shadows. The shadowed identity is recovered separately via Token::noexpand_shadowed (delimited matching only). Use this anywhere a token’s name keys a meaning lookup or a “same control sequence?” comparison. Cheap on the common path: non-CS tokens short-circuit before any string access.

opened_sources_snapshot

Snapshot of the opened-sources read-log (see record_opened_source).

pop_daemon_frame

pop_frame

Ends the current level of grouping. Note that this is lower level than \egroup;

pop_value

pops the last value in a named Stored::VecDequeStored queue, if any

push_daemon_frame

push_frame

push_pending_resource

push_tokens

Pushes Tokens into a Stored::Tokens value when defined, or assigns when new.

push_value

manage a (global) list of values

record_opened_source

Record a named source in the opened-sources read-log. Called from Mouth::create for file and cached-content mouths — a cold path (one call per file open, not per token).

remove_meaning_global

Remove a token’s meaning entirely — the token becomes undefined, as if it had never been defined, so a later use takes the normal undefined-CS error path naming the token itself. Bypasses the group-undo journal: intended ONLY for format-bootstrap time (no user groups open), where a format layer retracts a definition inherited from a lower layer that the emulated format must not expose (e.g. plain.tex’s \+ in a LaTeX session — real LaTeX is INITEX-based and never defines it).

remove_value

inline lookup_value after which globally assign an empty Tokens() to undo

remove_value_sym

remove_value variant for hot call sites with a pre-pinned SymStr (see crate::pin!) — added for after_assignment, which fires on every \def/\let/register assignment.

remove_vecdeque

reset_pending_resources

reset_thread_state

Free every definition/register/box this thread accumulated, returning all three State singletons (STATE, STD_STATE, STY_STATE) to a fresh, empty baseline and the rotation to Main.

search_paths_push_front

Global prepend (Perl UnshiftValue(SEARCHPATHS)) — a persistent search dir.

set_bindings_dispatch

set_extra_bindings_dispatch

set_indirect_model

set_input_encoding

set_label_mapping_hook

set_nomathparse_flag

set_prefix

Set one of the definition prefixes global, etc (only global matters!)

set_search_paths

Replace SEARCHPATHS GLOBALLY (Perl AssignValue(SEARCHPATHS => [...], 'global')). For the local-by-default \import scoping, use set_search_paths_local.

set_search_paths_local

Replace SEARCHPATHS in the CURRENT group only (Perl AssignValue(SEARCHPATHS => [...]) default-local): reverted when the enclosing \import/\subimport group closes. This is what makes import.sty faithful without an explicit save/restore stack.

set_source_map_flag

set_state

shift_value

snapshot_top_frame_meaning_keys

Snapshot of the keys currently bound at the topmost (calling) undo frame for the Meaning table. Used by Perl-style autoload triggers that need to promote everything a package’s load just installed at this scope to GLOBAL — without that promotion, sibling autoload triggers fired AFTER a group pop would re-fire on a now-undefined sibling CS (the canonical case is \begin{subequations} triggering amsmath autoload at depth=N, then a later \begin{align} at depth=0 finding \align undefined because amsmath’s depth=N install was popped on \end{subequations}).

source_map_enabled

Whether source-locator (--source-map) tracking + emission is on. Read by the source-provenance machinery (mouth token-start capture, Document::absorb data-sourcepos stamping) to stay zero-cost when off. See docs/performance/SOURCE_PROVENANCE.md.

source_table_snapshot

Snapshot of the sources table (index = tag) for emitting the document-level tag→file header.

source_tag

Find-or-append a source file in the document-level sources table, returning its integer tag (index). The per-element data-sourcepos attribute carries this compact integer rather than a path — the Source-Map-v3 sources convention (compact + anonymisable). Only called on the source-map path. See docs/performance/SOURCE_PROVENANCE.md §0.1.

stage_snapshot

Take a snapshot now and store it under a named key for later retrieval. Intended for phased engine init (e.g. stage_snapshot("bootstrap") called right after latex_bootstrap has loaded).

stage_snapshot_value

Stage an already-taken snapshot under a named key. Used by callers (like ini_tex) that want to snapshot at a specific point without waiting for a pool hook.

subfile_scope_at_depth

Named scope bracketing a subfile LaTeXML included itself — a standalone child’s preamble, an \imported file. Real LaTeX has no group at either spot (standalone gobbles the child preamble; import restores its paths by plain \def after the \input), so a package loaded inside one is an artifact of LaTeXML executing what the real packages skip. Bindings that open such a bracket activate this scope; require_package reads it to decide whether a load must outlive the bracket. See OXIDIZED_DESIGN #65.

subfile_scope_here

The subfile scope for the CURRENT frame depth — what a bracket activates on opening, and what require_package tests before hoisting.

take_pending_resources

take_snapshot

Take a snapshot of the current State (for dump diff).

try_lookup_int

lookup_int variant that never panics on a live mutable borrow.

undo_depth

Undo-stack depth (open TeX groups) — pass-1 streaming telemetry.

unshift_value

use_main_state

use_std_state

use_sty_state

with_font_info

with_mapping

manage a (global) hash of values

with_mapping_keys

with_mapping_sym

with_meaning

Closure-based variant of lookup_meaning — avoids the per-call Stored::clone() when the caller only needs to inspect the meaning (e.g. extract a CS Token from an Expandable/Primitive definition). Stored::clone is ~1% of total instructions on siunitx-heavy fixtures (5M+ calls per run, each cloning a full Stored enum). This helper borrows the stored value instead.

with_search_paths

with_stacked_values

with_stacked_values_sym

Sym-keyed variant of with_stacked_values.

with_tag_property

with_tag_property_mut

with_value

with_value_mut

with_value_sym

Sym-keyed variant of with_value — avoids the per-call arena::pin(key).

with_vecdeque

x_equals

XEquals check for two token arguments

Type Aliases

AssignmentCount

Ledger for stacked assignments

StashTable

The (table_name, key, value) contents of a stored table of assignments

Table

The type of values that are storable by the different namespaced “tables” in State.